tollgate-skill 1.0.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,18 @@
+{
+  "name": "tollgate",
+  "owner": { "name": "Tollgate", "url": "https://tollgateai.com" },
+  "plugins": [
+    {
+      "name": "tollgate",
+      "description": "Real-time gross-margin observability for AI agents. Wraps any LLM provider with cost + margin tracking in 2 lines.",
+      "category": "development",
+      "source": {
+        "source": "git",
+        "url": "https://github.com/Tollgateai/tollgate-skill.git",
+        "ref": "main"
+      },
+      "skills": ["./claude-code"],
+      "homepage": "https://github.com/Tollgateai/tollgate-skill"
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "tollgate",
+  "description": "Real-time gross-margin observability for AI agents. Wraps any LLM provider with cost + margin tracking in 2 lines.",
+  "version": "1.0.0",
+  "author": { "name": "Tollgate", "url": "https://tollgateai.com" },
+  "keywords": ["ai", "cost", "margin", "observability", "llm", "agents"],
+  "homepage": "https://github.com/Tollgateai/tollgate-skill"
+}

package/README.md

@@ -0,0 +1,114 @@
+# tollgate-skill
+
+> AI coding tool instructions for integrating [Tollgate](https://www.tollgateai.dev) — real-time gross-margin observability for AI products.
+
+Works with **Claude Code**, **Cursor**, **GitHub Copilot**, **Windsurf**, and **Codex**. One install, your AI coding assistant knows how to wire up Tollgate correctly.
+
+---
+
+## What this does
+
+Once installed, your AI coding assistant can:
+- Wrap any LLM provider client (Anthropic, OpenAI, Gemini, Bedrock, OpenRouter…) with Tollgate tracking in 2 lines
+- Set `idempotencyKey`, `reasoningTokens`, `cachedTokens` correctly
+- Handle multi-step agents and run outcomes
+- Configure streaming correctly for each provider
+- Keep prompt content out of the tracking payload
+
+---
+
+## Install
+
+### Claude Code
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Tollgateai/tollgate-skill/main/install.sh | bash -s -- --tool claude
+```
+
+Installs to `~/.claude/skills/tollgate/SKILL.md`. Restart Claude Code, then type `/tollgate` to activate.
+
+### Cursor
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Tollgateai/tollgate-skill/main/install.sh | bash -s -- --tool cursor
+```
+
+Installs to `.cursor/rules/tollgate.mdc` in your project. Cursor picks it up automatically when relevant.
+
+### GitHub Copilot
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Tollgateai/tollgate-skill/main/install.sh | bash -s -- --tool copilot
+```
+
+Appends to (or creates) `.github/copilot-instructions.md` in your project.
+
+### Windsurf
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Tollgateai/tollgate-skill/main/install.sh | bash -s -- --tool windsurf
+```
+
+Installs to `.windsurf/rules/tollgate.md` in your project.
+
+### Codex
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Tollgateai/tollgate-skill/main/install.sh | bash -s -- --tool codex
+```
+
+Appends to (or creates) `AGENTS.md` in your project.
+
+### All tools at once
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Tollgateai/tollgate-skill/main/install.sh | bash -s -- --tool all
+```
+
+---
+
+## Manual install
+
+| Tool | Copy this file to... |
+|---|---|
+| Claude Code | `~/.claude/skills/tollgate/SKILL.md` |
+| Cursor | `.cursor/rules/tollgate.mdc` |
+| GitHub Copilot | `.github/copilot-instructions.md` |
+| Windsurf | `.windsurf/rules/tollgate.md` |
+| Codex | `AGENTS.md` (project root) |
+
+---
+
+## What you'll need
+
+- A Tollgate account — [sign up at tollgateai](https://www.tollgateai.dev)
+- An API key from **Settings → API Keys** (prefix: `tg_live_…`)
+- The Tollgate SDK: `npm install @tollgateai/sdk` or `pip install tollgateai`
+
+---
+
+## Repo structure
+
+```
+tollgate-skill/
+  claude-code/
+    SKILL.md          Claude Code skill (YAML frontmatter + full integration guide)
+  cursor/
+    tollgate.mdc      Cursor rule (.mdc format with glob config)
+  copilot/
+    copilot-instructions.md   GitHub Copilot workspace instructions
+  windsurf/
+    tollgate.md       Windsurf rule
+  codex/
+    AGENTS.md         OpenAI Codex agent instructions
+  install.sh          One-liner installer for all tools
+```
+
+---
+
+## Links
+
+- [Tollgate Dashboard](https://www.tollgateai.dev/dashboard)
+- [SDK — @tollgateai/sdk](https://www.npmjs.com/package/@tollgateai/sdk) · [source](https://github.com/Tollgateai/tollgate-sdk/tree/main/packages/tollgate-sdk-ts)
+- [Python SDK — tollgateai](https://pypi.org/project/tollgateai/) · [source](https://github.com/Tollgateai/tollgate-sdk/tree/main/packages/tollgate-sdk-python)
+- [Docs](https://www.tollgateai.dev/docs)

package/bin/tollgate-skill.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const args = process.argv.slice(2);
+const toolFlagIndex = args.indexOf('--tool');
+const tool = toolFlagIndex !== -1 ? args[toolFlagIndex + 1] : (args[0] || '');
+
+const ROOT = path.join(__dirname, '..');
+
+function copyFile(src, dest) {
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.copyFileSync(src, dest);
+}
+
+function appendOrCreate(src, dest) {
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  const content = fs.readFileSync(src, 'utf8');
+  if (fs.existsSync(dest)) {
+    fs.appendFileSync(dest, '\n' + content);
+    return 'appended to';
+  }
+  fs.writeFileSync(dest, content);
+  return 'created at';
+}
+
+function installClaude() {
+  const dest = path.join(os.homedir(), '.claude', 'skills', 'tollgate', 'SKILL.md');
+  copyFile(path.join(ROOT, 'claude-code', 'SKILL.md'), dest);
+  console.log(`Claude Code: skill installed at ${dest}`);
+  console.log('  Restart Claude Code, then use /tollgate to activate.');
+}
+
+function installCursor() {
+  const dest = path.join(process.cwd(), '.cursor', 'rules', 'tollgate.mdc');
+  copyFile(path.join(ROOT, 'cursor', 'tollgate.mdc'), dest);
+  console.log(`Cursor: rule installed at ${dest}`);
+}
+
+function installCopilot() {
+  const dest = path.join(process.cwd(), '.github', 'copilot-instructions.md');
+  const action = appendOrCreate(path.join(ROOT, 'copilot', 'copilot-instructions.md'), dest);
+  console.log(`Copilot: instructions ${action} ${dest}`);
+}
+
+function installWindsurf() {
+  const dest = path.join(process.cwd(), '.windsurf', 'rules', 'tollgate.md');
+  copyFile(path.join(ROOT, 'windsurf', 'tollgate.md'), dest);
+  console.log(`Windsurf: rule installed at ${dest}`);
+}
+
+function installCodex() {
+  const dest = path.join(process.cwd(), 'AGENTS.md');
+  const action = appendOrCreate(path.join(ROOT, 'codex', 'AGENTS.md'), dest);
+  console.log(`Codex: AGENTS.md ${action} ${dest}`);
+}
+
+function usage() {
+  console.log('Tollgate skill installer\n');
+  console.log('Usage:');
+  console.log('  npx tollgate-skill --tool claude     # Claude Code  (~/.claude/skills/tollgate/)');
+  console.log('  npx tollgate-skill --tool cursor     # Cursor        (.cursor/rules/tollgate.mdc)');
+  console.log('  npx tollgate-skill --tool copilot    # GitHub Copilot (.github/copilot-instructions.md)');
+  console.log('  npx tollgate-skill --tool windsurf   # Windsurf      (.windsurf/rules/tollgate.md)');
+  console.log('  npx tollgate-skill --tool codex      # Codex          (AGENTS.md)');
+  console.log('  npx tollgate-skill --tool all        # All of the above');
+}
+
+switch (tool) {
+  case 'claude':   installClaude(); break;
+  case 'cursor':   installCursor(); break;
+  case 'copilot':  installCopilot(); break;
+  case 'windsurf': installWindsurf(); break;
+  case 'codex':    installCodex(); break;
+  case 'all':
+    installClaude();
+    installCursor();
+    installCopilot();
+    installWindsurf();
+    installCodex();
+    break;
+  default:
+    usage();
+    console.log('\nDefaulting to Claude Code:');
+    installClaude();
+}

package/claude-code/SKILL.md

@@ -0,0 +1,331 @@
+---
+name: tollgate
+description: Integrate Tollgate to track LLM costs per customer and monitor gross margin in real time. Use when the user wants to add Tollgate to their AI product.
+version: 1.0.0
+---
+
+# Tollgate Integration Skill
+
+Tollgate is a **real-time gross-margin observability** layer for AI products. It joins LLM provider costs with your revenue config to show per-customer, per-agent, per-run margins — so you know which customers are profitable and which are not.
+
+> "Stripe/Orb tells you what to charge. Tollgate tells you if you're making money."
+
+## When to use this skill
+
+Trigger on phrases like:
+- "integrate Tollgate", "add Tollgate tracking", "set up cost tracking"
+- "track LLM costs per customer", "monitor gross margin"
+- "instrument my AI agent with Tollgate"
+
+---
+
+## What Tollgate tracks
+
+Each call to `POST /api/track` records one **usage event** — a single LLM call, tool call, or retrieval step — attributed to a customer and run. Tollgate:
+
+1. Writes the raw event to DynamoDB (idempotent, ~1 ms hot path)
+2. Looks up the provider rate card to compute cost in cents
+3. Looks up the customer's plan to compute recognized revenue
+4. Rolls up `costCents`, `revenueCents`, `marginCents`, `marginPct` per customer/day/run
+
+The dashboard shows live per-customer gross margin, margin-leak flags, and trend charts.
+
+---
+
+## Quick start (3 steps)
+
+### Step 1 — Get an API key
+
+Generate a key in **Settings → API Keys** (prefix: `tg_live_…`). Set it as an environment variable:
+
+```bash
+TOLLGATE_API_KEY=tg_live_your_key_here
+```
+
+### Step 2 — Install the SDK
+
+```bash
+# TypeScript / Node.js
+npm install @tollgateai/sdk
+# or: pnpm add @tollgateai/sdk  |  yarn add @tollgateai/sdk
+
+# Python
+pip install tollgateai
+```
+
+### Step 3 — Wrap your provider client
+
+Pick the snippet for your provider. Tollgate intercepts the response, extracts token counts, and fires `POST /api/track` in the background.
+
+---
+
+## Provider integration examples
+
+### Anthropic (TypeScript)
+
+```typescript
+import Anthropic from '@anthropic-ai/sdk';
+import { createTollgateClient, wrapAnthropic } from '@tollgateai/sdk';
+
+const tollgate = createTollgateClient(); // reads TOLLGATE_API_KEY
+const anthropic = wrapAnthropic(new Anthropic(), tollgate, {
+  customerId: 'cust_acme',       // your external customer id — required
+  runId: 'ticket_8842',          // your run/session id — recommended
+  agentId: 'support-agent',      // optional: which agent within the run
+});
+
+// Use anthropic exactly as before — no changes needed below this line.
+const msg = await anthropic.messages.create({
+  model: 'claude-opus-4-8',
+  max_tokens: 1024,
+  messages: [{ role: 'user', content: 'Hello' }],
+});
+```
+
+### OpenAI (TypeScript)
+
+```typescript
+import OpenAI from 'openai';
+import { createTollgateClient, wrapOpenAI } from '@tollgateai/sdk';
+
+const tollgate = createTollgateClient();
+const openai = wrapOpenAI(new OpenAI(), tollgate, {
+  customerId: 'cust_acme',
+  runId: 'ticket_8842',
+});
+```
+
+### OpenAI-compatible gateways (Groq, OpenRouter, Vercel AI Gateway, vLLM, Together, Fireworks)
+
+```typescript
+import OpenAI from 'openai';
+import { createTollgateClient, wrapOpenAI } from '@tollgateai/sdk';
+
+const tollgate = createTollgateClient();
+const groq = wrapOpenAI(
+  new OpenAI({ baseURL: 'https://api.groq.com/openai/v1', apiKey: process.env.GROQ_API_KEY }),
+  tollgate,
+  { customerId: 'cust_acme', runId: 'ticket_8842', provider: 'openai_compatible' },
+);
+```
+
+### Google Gemini (TypeScript)
+
+```typescript
+import { GoogleGenAI } from '@google/genai';
+import { createTollgateClient, wrapGemini } from '@tollgateai/sdk';
+
+const tollgate = createTollgateClient();
+const gemini = wrapGemini(new GoogleGenAI({ apiKey: process.env.GOOGLE_API_KEY }), tollgate, {
+  customerId: 'cust_acme',
+  runId: 'ticket_8842',
+});
+```
+
+### AWS Bedrock (TypeScript)
+
+```typescript
+import { BedrockRuntimeClient } from '@aws-sdk/client-bedrock-runtime';
+import { createTollgateClient, wrapBedrock } from '@tollgateai/sdk';
+
+const tollgate = createTollgateClient();
+const bedrock = wrapBedrock(new BedrockRuntimeClient({ region: 'us-east-1' }), tollgate, {
+  customerId: 'cust_acme',
+  runId: 'ticket_8842',
+});
+```
+
+### Anthropic (Python)
+
+```python
+import anthropic
+from tollgate import create_tollgate_client, wrap_anthropic
+
+tollgate = create_tollgate_client()  # reads TOLLGATE_API_KEY
+client = wrap_anthropic(
+    anthropic.Anthropic(), tollgate,
+    customer_id="cust_acme",
+    run_id="ticket_8842",
+)
+```
+
+### OpenAI (Python)
+
+```python
+from openai import OpenAI
+from tollgate import create_tollgate_client, wrap_openai
+
+tollgate = create_tollgate_client()
+client = wrap_openai(OpenAI(), tollgate, customer_id="cust_acme", run_id="ticket_8842")
+```
+
+---
+
+## Streaming
+
+The wrapper handles streaming automatically. **OpenAI / OpenAI-compatible only:** add `stream_options: { include_usage: true }` or token counts won't be captured.
+
+```typescript
+const stream = await openai.chat.completions.create({
+  model: 'gpt-4o',
+  messages: [{ role: 'user', content: 'Hello' }],
+  stream: true,
+  stream_options: { include_usage: true }, // required for Tollgate
+});
+```
+
+---
+
+## Multi-step agents — closing a run
+
+A **run** (`runId`) groups all LLM calls for one end-to-end task. Set `outcome` on the final step to close the run and gate outcome-priced revenue.
+
+```typescript
+await tollgate.resolve({
+  runId: 'ticket_8842',
+  customerId: 'cust_acme',
+  outcome: 'resolved',       // 'resolved' | 'escalated' | 'failed'
+  revenueUnitCents: 50,      // $0.50 per resolved ticket
+});
+```
+
+- `resolved` — task done; outcome-priced revenue is recognized.
+- `escalated` / `failed` — no activity revenue recognized, but all costs are tracked. Makes unprofitable runs visible.
+- Omitting `outcome` on a single-call run treats it as `resolved`.
+
+---
+
+## Manual tracking (no wrapper)
+
+```typescript
+await tollgate.track({
+  customerId: 'cust_acme',
+  runId: 'ticket_8842',
+  provider: 'anthropic',   // 'anthropic' | 'openai' | 'openai_compatible' | 'bedrock' | 'google'
+  model: 'claude-opus-4-8',
+  tokensIn: response.usage.input_tokens,
+  tokensOut: response.usage.output_tokens,
+  reasoningTokens: response.usage.cache_creation_input_tokens ?? 0,
+  cachedTokens: response.usage.cache_read_input_tokens ?? 0,
+  idempotencyKey: `${runId}#step_1`,  // stable, unique per event
+  latencyMs: Date.now() - startTime,
+});
+```
+
+### REST
+
+```bash
+curl -X POST https://www.tollgateai.dev/api/track \
+  -H "Authorization: Bearer tg_live_your_key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "customerId": "cust_acme",
+    "runId": "ticket_8842",
+    "provider": "anthropic",
+    "model": "claude-opus-4-8",
+    "tokensIn": 1200,
+    "tokensOut": 340,
+    "idempotencyKey": "ticket_8842#step_1"
+  }'
+```
+
+Response: `{ "status": "created", "eventId": "..." }` or `{ "status": "duplicate" }` (safe to ignore).
+
+---
+
+## Full field reference
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `customerId` | string | ✅ | Your external customer id. |
+| `runId` | string | ✅ | Groups all LLM calls for one task/session. |
+| `provider` | string | ✅ | `anthropic` `openai` `openai_compatible` `bedrock` `google` |
+| `model` | string | ✅ | Model name as returned by provider. |
+| `idempotencyKey` | string | ✅ | Unique per event — prevents double-counting on retries. Pattern: `runId#step_N`. |
+| `agentId` | string | — | Which agent within the run. |
+| `type` | string | — | `llm` (default) `tool` `retrieval` |
+| `tokensIn` | int | — | Standard (non-cached) input tokens. |
+| `tokensOut` | int | — | Output tokens. |
+| `reasoningTokens` | int | — | Thinking/reasoning tokens — billed at output rate. |
+| `cachedTokens` | int | — | Cache-read input tokens — billed at reduced rate. |
+| `cacheWrite5mTokens` | int | — | Cache-write tokens, 5-min TTL. |
+| `cacheWrite1hTokens` | int | — | Cache-write tokens, 1-hour TTL. |
+| `toolCalls` | int | — | Number of tool calls. |
+| `toolName` | string | — | Tool name for per-tool breakdown. |
+| `audioTokensIn` | int | — | Audio input tokens (OpenAI Realtime). |
+| `audioTokensOut` | int | — | Audio output tokens. |
+| `imageTokensIn` | int | — | Image/vision input tokens. |
+| `imageTokensOut` | int | — | Image generation output tokens. |
+| `videoTokensIn` | int | — | Video input tokens (Gemini). |
+| `webSearchRequests` | int | — | Web search calls (Anthropic/Gemini grounding). |
+| `latencyMs` | int | — | Request latency in milliseconds. |
+| `externalCostCents` | float | — | Cost of external tools used (image gen APIs, sandboxes). Added directly to cost. |
+| `providerCostCents` | float | — | Exact cost from provider/gateway — skips rate-card lookup. |
+| `outcome` | string | — | `resolved` `escalated` `failed` — set only on the closing event. |
+| `revenueUnitCents` | int | — | Per-run revenue in cents. Overrides plan default. |
+| `ts` | ISO string | — | Event timestamp. Defaults to server receive time. |
+
+> **Privacy:** Never send prompt content. Fields like `prompt`, `messages`, `content`, `input`, `output` are rejected with HTTP 400.
+
+---
+
+## Error codes
+
+| Status | Meaning |
+|---|---|
+| 201 created | Event ingested. |
+| 200 duplicate | Same `idempotencyKey` already stored — ignore. |
+| 400 | Validation error or prompt content detected. |
+| 401 | Invalid or missing API key. |
+| 402 | Monthly event quota reached. |
+| 429 | Rate limit exceeded — check `Retry-After` header. |
+| 500 | Internal error — event may not have been stored. |
+
+---
+
+## Register a customer before first usage (optional but recommended)
+
+Call `upsertCustomer()` before sending any usage events so the plan is ready and revenue is recognized from event one. This is especially important for `usage_based` pricing, where revenue is computed at ingest time.
+
+```typescript
+await tollgate.upsertCustomer({
+  externalId: 'cust_acme',          // must match the customerId used in track/wrap
+  name: 'Acme Corp',
+  plan: {
+    name: 'Growth',
+    pricingModel: 'per_unit',        // 'per_unit' | 'per_resolution' | 'usage_based' | 'per_seat' | 'flat' | 'hybrid'
+    unitRevenueCents: 50,            // $0.50 per resolved ticket
+    baseRevenueCents: 0,
+  },
+});
+```
+
+---
+
+## Integration checklist
+
+- [ ] `TOLLGATE_API_KEY` set in environment (never commit it)
+- [ ] Provider client wrapped (or `tollgate.track()` called after each LLM call)
+- [ ] `customerId` matches real customer ids in your system
+- [ ] `runId` consistently identifies one end-to-end task
+- [ ] `idempotencyKey` is stable and unique per event
+- [ ] `reasoningTokens` included for extended thinking models (Claude 3.7+, o1, o3)
+- [ ] `cachedTokens` included if using prompt caching
+- [ ] `outcome` set on the closing event for per_unit / hybrid plans
+- [ ] No prompt content in any field
+
+---
+
+## Implementation approach
+
+When helping a user integrate Tollgate:
+
+1. Ask which provider(s) they use (Anthropic / OpenAI / Gemini / Bedrock / gateway).
+2. Ask which language (TypeScript / Python / other).
+3. Find where they create the provider client — show the 2-line wrap.
+4. If they have multi-step agents, identify the final step and add `resolve()`.
+5. If they use OpenAI streaming, add `stream_options: { include_usage: true }`.
+6. Confirm `customerId` maps to real customer ids in their system.
+7. Remind them to add `TOLLGATE_API_KEY` to `.env` and `.gitignore`.
+
+The wrapper never modifies the response the user's code sees, never blocks on Tollgate errors, and always passes through to the original provider.

package/codex/AGENTS.md

@@ -0,0 +1,150 @@
+# Tollgate Integration
+
+When asked to integrate Tollgate, add LLM cost tracking, or set up gross-margin observability, follow these instructions.
+
+Tollgate tracks LLM provider costs per customer in real time and joins them with revenue config to show gross margin per customer, agent, and run.
+
+## Setup
+
+Set the API key (get it from Settings → API Keys on the Tollgate dashboard):
+
+```
+TOLLGATE_API_KEY=tg_live_your_key_here
+```
+
+Install the SDK:
+
+```bash
+npm install @tollgateai/sdk     # TypeScript / Node.js
+pip install tollgateai           # Python
+```
+
+## Wrap the provider client
+
+Find where the user creates their provider client. Replace the client with a wrapped version. The wrapper is transparent — it never changes the response shape or blocks on errors.
+
+**Anthropic (TypeScript):**
+```typescript
+import Anthropic from '@anthropic-ai/sdk';
+import { createTollgateClient, wrapAnthropic } from '@tollgateai/sdk';
+
+const tollgate = createTollgateClient();
+const anthropic = wrapAnthropic(new Anthropic(), tollgate, {
+  customerId: 'cust_acme',
+  runId: 'ticket_8842',
+});
+```
+
+**OpenAI (TypeScript):**
+```typescript
+import OpenAI from 'openai';
+import { createTollgateClient, wrapOpenAI } from '@tollgateai/sdk';
+
+const tollgate = createTollgateClient();
+const openai = wrapOpenAI(new OpenAI(), tollgate, { customerId: 'cust_acme', runId: 'ticket_8842' });
+```
+
+**OpenAI-compatible (Groq, OpenRouter, vLLM, Together, Fireworks):**
+```typescript
+const client = wrapOpenAI(
+  new OpenAI({ baseURL: 'https://api.groq.com/openai/v1', apiKey: process.env.GROQ_API_KEY }),
+  tollgate,
+  { customerId: 'cust_acme', runId: 'ticket_8842', provider: 'openai_compatible' },
+);
+```
+
+**Google Gemini (TypeScript):**
+```typescript
+import { GoogleGenAI } from '@google/genai';
+import { createTollgateClient, wrapGemini } from '@tollgateai/sdk';
+const gemini = wrapGemini(new GoogleGenAI({ apiKey: process.env.GOOGLE_API_KEY }), tollgate, { customerId: 'cust_acme', runId: 'ticket_8842' });
+```
+
+**AWS Bedrock (TypeScript):**
+```typescript
+import { BedrockRuntimeClient } from '@aws-sdk/client-bedrock-runtime';
+import { createTollgateClient, wrapBedrock } from '@tollgateai/sdk';
+const bedrock = wrapBedrock(new BedrockRuntimeClient({ region: 'us-east-1' }), tollgate, { customerId: 'cust_acme', runId: 'ticket_8842' });
+```
+
+**Anthropic (Python):**
+```python
+import anthropic
+from tollgate import create_tollgate_client, wrap_anthropic
+
+tollgate = create_tollgate_client()
+client = wrap_anthropic(anthropic.Anthropic(), tollgate, customer_id="cust_acme", run_id="ticket_8842")
+```
+
+**OpenAI (Python):**
+```python
+from openai import OpenAI
+from tollgate import create_tollgate_client, wrap_openai
+
+tollgate = create_tollgate_client()
+client = wrap_openai(OpenAI(), tollgate, customer_id="cust_acme", run_id="ticket_8842")
+```
+
+## Streaming (OpenAI and OpenAI-compatible only)
+
+Add `stream_options: { include_usage: true }` — otherwise Tollgate cannot see token counts during streaming.
+
+```typescript
+const stream = await openai.chat.completions.create({
+  model: 'gpt-4o',
+  messages: [...],
+  stream: true,
+  stream_options: { include_usage: true },
+});
+```
+
+## Closing a multi-step run
+
+When a run has multiple LLM calls, call `resolve()` after the final step:
+
+```typescript
+await tollgate.resolve({
+  runId: 'ticket_8842',
+  customerId: 'cust_acme',
+  outcome: 'resolved',       // 'resolved' | 'escalated' | 'failed'
+  revenueUnitCents: 50,      // $0.50 per resolved ticket
+});
+```
+
+Use `escalated` or `failed` when the task did not complete successfully. Tollgate still tracks the cost but suppresses activity revenue, making the margin drag visible.
+
+## Manual tracking (no wrapper available)
+
+```typescript
+await tollgate.track({
+  customerId: 'cust_acme',
+  runId: 'ticket_8842',
+  provider: 'anthropic',
+  model: 'claude-opus-4-8',
+  tokensIn: 1200,
+  tokensOut: 340,
+  reasoningTokens: 0,
+  cachedTokens: 0,
+  idempotencyKey: `ticket_8842#step_1`,
+  latencyMs: 820,
+});
+```
+
+## Rules to follow
+
+- `idempotencyKey` must be stable and unique per event. Use `runId#step_N`. Duplicates are safely dropped.
+- Never include prompt content in any field. Fields like `messages`, `content`, `input`, `output` are rejected with HTTP 400.
+- Pass `reasoningTokens` separately — they bill at the output token rate.
+- Pass `cachedTokens` separately — they bill at a reduced rate.
+- Set `outcome` only on the closing event of a run.
+
+## Error codes
+
+- 201: event stored
+- 200 duplicate: already stored, ignore
+- 400: validation error or prompt content detected
+- 401: bad API key
+- 402: quota reached
+- 429: rate limited — check Retry-After header
+
+Full docs: https://www.tollgateai.dev/docs

package/copilot/copilot-instructions.md

@@ -0,0 +1,137 @@
+# Tollgate Integration Instructions
+
+When asked to integrate Tollgate, track LLM costs per customer, or add gross-margin observability, follow these instructions.
+
+## What Tollgate does
+
+Tollgate wraps your LLM provider client and tracks every API call — tokens in, tokens out, reasoning tokens, latency — and attributes them to a customer and run. It joins cost (from provider rate cards) with revenue (from your plan config) to show real-time gross margin per customer in a dashboard.
+
+## Required setup
+
+Get an API key from the Tollgate dashboard (Settings → API Keys). Add it to the environment:
+
+```
+TOLLGATE_API_KEY=tg_live_your_key_here
+```
+
+Install:
+
+```bash
+npm install @tollgateai/sdk    # TypeScript
+pip install tollgateai          # Python
+```
+
+## Wrap the provider client — TypeScript
+
+**Anthropic:**
+```typescript
+import Anthropic from '@anthropic-ai/sdk';
+import { createTollgateClient, wrapAnthropic } from '@tollgateai/sdk';
+
+const tollgate = createTollgateClient();
+const anthropic = wrapAnthropic(new Anthropic(), tollgate, {
+  customerId: 'cust_acme',  // your external customer id — required
+  runId: 'ticket_8842',     // groups all LLM calls for one task
+});
+// Use anthropic normally — tracking is automatic.
+```
+
+**OpenAI:**
+```typescript
+import OpenAI from 'openai';
+import { createTollgateClient, wrapOpenAI } from '@tollgateai/sdk';
+
+const tollgate = createTollgateClient();
+const openai = wrapOpenAI(new OpenAI(), tollgate, { customerId: 'cust_acme', runId: 'ticket_8842' });
+```
+
+**OpenAI-compatible (Groq, OpenRouter, vLLM, Together, Fireworks):**
+```typescript
+const client = wrapOpenAI(
+  new OpenAI({ baseURL: 'https://api.groq.com/openai/v1', apiKey: process.env.GROQ_API_KEY }),
+  tollgate,
+  { customerId: 'cust_acme', runId: 'ticket_8842', provider: 'openai_compatible' },
+);
+```
+
+**Google Gemini:**
+```typescript
+import { GoogleGenAI } from '@google/genai';
+import { createTollgateClient, wrapGemini } from '@tollgateai/sdk';
+const gemini = wrapGemini(new GoogleGenAI({ apiKey: process.env.GOOGLE_API_KEY }), tollgate, { customerId: 'cust_acme', runId: 'ticket_8842' });
+```
+
+**AWS Bedrock:**
+```typescript
+import { BedrockRuntimeClient } from '@aws-sdk/client-bedrock-runtime';
+import { createTollgateClient, wrapBedrock } from '@tollgateai/sdk';
+const bedrock = wrapBedrock(new BedrockRuntimeClient({ region: 'us-east-1' }), tollgate, { customerId: 'cust_acme', runId: 'ticket_8842' });
+```
+
+## Wrap the provider client — Python
+
+```python
+from tollgate import create_tollgate_client, wrap_anthropic, wrap_openai
+
+tollgate = create_tollgate_client()
+
+# Anthropic
+import anthropic
+client = wrap_anthropic(anthropic.Anthropic(), tollgate, customer_id="cust_acme", run_id="ticket_8842")
+
+# OpenAI
+from openai import OpenAI
+client = wrap_openai(OpenAI(), tollgate, customer_id="cust_acme", run_id="ticket_8842")
+```
+
+## OpenAI streaming — required flag
+
+```typescript
+const stream = await openai.chat.completions.create({
+  model: 'gpt-4o',
+  messages: [...],
+  stream: true,
+  stream_options: { include_usage: true }, // required — Tollgate won't see tokens without this
+});
+```
+
+## Closing a multi-step run
+
+After the final LLM call in a task, call resolve():
+
+```typescript
+await tollgate.resolve({
+  runId: 'ticket_8842',
+  customerId: 'cust_acme',
+  outcome: 'resolved',     // 'resolved' | 'escalated' | 'failed'
+  revenueUnitCents: 50,    // cents — $0.50 per resolved ticket
+});
+```
+
+## Important rules
+
+- `idempotencyKey` must be unique per event (pattern: `runId#step_N`). Duplicates are safely ignored.
+- Never send prompt content. Fields like `messages`, `content`, `input`, `output` are rejected.
+- `reasoningTokens` (thinking/extended-thinking) bills at output rate — always pass separately.
+- `cachedTokens` bills at reduced rate — always pass separately.
+- `outcome` goes only on the final event of a run.
+
+## Direct API call (any language)
+
+```
+POST https://www.tollgateai.dev/api/track
+Authorization: Bearer tg_live_…
+Content-Type: application/json
+
+{
+  "customerId": "cust_acme",
+  "runId": "ticket_8842",
+  "provider": "anthropic",
+  "model": "claude-opus-4-8",
+  "tokensIn": 1200,
+  "tokensOut": 340,
+  "idempotencyKey": "ticket_8842#step_1"
+}
+```
+
+Full reference: https://www.tollgateai.dev/docs

package/cursor/tollgate.mdc

@@ -0,0 +1,141 @@
+---
+description: Instructions for integrating Tollgate LLM cost tracking and gross-margin observability into AI products. Apply when the user asks to add Tollgate, track LLM costs per customer, or monitor gross margin.
+globs: []
+alwaysApply: false
+---
+
+# Tollgate Integration
+
+Tollgate tracks LLM provider costs per customer and joins them with revenue to show real-time gross margin. One wrap of your provider client is all it takes.
+
+## Setup
+
+```bash
+TOLLGATE_API_KEY=tg_live_your_key_here
+```
+
+```bash
+npm install @tollgateai/sdk   # TypeScript
+pip install tollgateai        # Python
+```
+
+## Wrap your provider (TypeScript)
+
+**Anthropic:**
+```typescript
+import Anthropic from '@anthropic-ai/sdk';
+import { createTollgateClient, wrapAnthropic } from '@tollgateai/sdk';
+
+const tollgate = createTollgateClient();
+const anthropic = wrapAnthropic(new Anthropic(), tollgate, {
+  customerId: 'cust_acme',  // required — your external customer id
+  runId: 'ticket_8842',     // groups all calls for one task
+});
+// Use anthropic normally — Tollgate tracks in the background.
+```
+
+**OpenAI:**
+```typescript
+import OpenAI from 'openai';
+import { createTollgateClient, wrapOpenAI } from '@tollgateai/sdk';
+
+const tollgate = createTollgateClient();
+const openai = wrapOpenAI(new OpenAI(), tollgate, { customerId: 'cust_acme', runId: 'ticket_8842' });
+```
+
+**OpenAI-compatible gateways (Groq, OpenRouter, vLLM, Together):**
+```typescript
+const client = wrapOpenAI(
+  new OpenAI({ baseURL: 'https://api.groq.com/openai/v1', apiKey: process.env.GROQ_API_KEY }),
+  tollgate,
+  { customerId: 'cust_acme', runId: 'ticket_8842', provider: 'openai_compatible' },
+);
+```
+
+**Google Gemini:**
+```typescript
+import { GoogleGenAI } from '@google/genai';
+import { createTollgateClient, wrapGemini } from '@tollgateai/sdk';
+const gemini = wrapGemini(new GoogleGenAI({ apiKey: process.env.GOOGLE_API_KEY }), tollgate, { customerId: 'cust_acme', runId: 'ticket_8842' });
+```
+
+**AWS Bedrock:**
+```typescript
+import { BedrockRuntimeClient } from '@aws-sdk/client-bedrock-runtime';
+import { createTollgateClient, wrapBedrock } from '@tollgateai/sdk';
+const bedrock = wrapBedrock(new BedrockRuntimeClient({ region: 'us-east-1' }), tollgate, { customerId: 'cust_acme', runId: 'ticket_8842' });
+```
+
+## Wrap your provider (Python)
+
+```python
+from tollgate import create_tollgate_client, wrap_anthropic, wrap_openai
+
+tollgate = create_tollgate_client()
+
+# Anthropic
+import anthropic
+client = wrap_anthropic(anthropic.Anthropic(), tollgate, customer_id="cust_acme", run_id="ticket_8842")
+
+# OpenAI
+from openai import OpenAI
+client = wrap_openai(OpenAI(), tollgate, customer_id="cust_acme", run_id="ticket_8842")
+```
+
+## Streaming (OpenAI only — required)
+
+```typescript
+const stream = await openai.chat.completions.create({
+  model: 'gpt-4o',
+  messages: [...],
+  stream: true,
+  stream_options: { include_usage: true }, // required for Tollgate to see token counts
+});
+```
+
+## Close a multi-step run with outcome
+
+```typescript
+await tollgate.resolve({
+  runId: 'ticket_8842',
+  customerId: 'cust_acme',
+  outcome: 'resolved',      // 'resolved' | 'escalated' | 'failed'
+  revenueUnitCents: 50,     // $0.50 per resolved ticket
+});
+```
+
+`escalated`/`failed` suppresses activity revenue but still tracks cost — making unprofitable runs visible on the dashboard.
+
+## Manual tracking (no wrapper)
+
+```typescript
+await tollgate.track({
+  customerId: 'cust_acme',
+  runId: 'ticket_8842',
+  provider: 'anthropic',        // 'anthropic' | 'openai' | 'openai_compatible' | 'bedrock' | 'google'
+  model: 'claude-opus-4-8',
+  tokensIn: 1200,
+  tokensOut: 340,
+  reasoningTokens: 0,           // thinking tokens — bill at output rate
+  cachedTokens: 0,              // cache-read tokens — reduced rate
+  idempotencyKey: `${runId}#step_1`,  // stable, unique per event
+  latencyMs: 820,
+});
+```
+
+## Key rules
+
+- `idempotencyKey` must be stable and unique per event (e.g. `runId#step_N`). Duplicates are silently dropped.
+- Never send prompt content (`messages`, `content`, `input`, `output` etc.) — rejected with HTTP 400.
+- `reasoningTokens` and `cachedTokens` must be passed separately — they bill at different rates.
+- `outcome` goes only on the **closing** event of a run.
+
+## REST endpoint
+
+```
+POST https://www.tollgateai.dev/api/track
+Authorization: Bearer tg_live_…
+Content-Type: application/json
+```
+
+Full field reference: https://www.tollgateai.dev/docs

package/install.sh

@@ -0,0 +1,86 @@
+#!/usr/bin/env bash
+# Tollgate skill installer
+# Usage: curl -fsSL https://raw.githubusercontent.com/Tollgateai/tollgate-skill/main/install.sh | sh
+# Or: bash install.sh [--tool claude|cursor|copilot|windsurf|codex|all]
+
+set -e
+
+REPO_URL="https://raw.githubusercontent.com/Tollgateai/tollgate-skill/main"
+TOOL="${1:-}"
+
+# Parse --tool flag
+if [ "$1" = "--tool" ]; then
+  TOOL="$2"
+fi
+
+install_claude_code() {
+  SKILL_DIR="${HOME}/.claude/skills/tollgate"
+  mkdir -p "$SKILL_DIR"
+  curl -fsSL "${REPO_URL}/claude-code/SKILL.md" -o "${SKILL_DIR}/SKILL.md"
+  echo "Claude Code: skill installed at ${SKILL_DIR}/SKILL.md"
+  echo "  Restart Claude Code, then use /tollgate to activate the skill."
+}
+
+install_cursor() {
+  mkdir -p ".cursor/rules"
+  curl -fsSL "${REPO_URL}/cursor/tollgate.mdc" -o ".cursor/rules/tollgate.mdc"
+  echo "Cursor: rule installed at .cursor/rules/tollgate.mdc"
+}
+
+install_copilot() {
+  mkdir -p ".github"
+  if [ -f ".github/copilot-instructions.md" ]; then
+    echo "" >> ".github/copilot-instructions.md"
+    curl -fsSL "${REPO_URL}/copilot/copilot-instructions.md" >> ".github/copilot-instructions.md"
+    echo "Copilot: appended to .github/copilot-instructions.md"
+  else
+    curl -fsSL "${REPO_URL}/copilot/copilot-instructions.md" -o ".github/copilot-instructions.md"
+    echo "Copilot: instructions created at .github/copilot-instructions.md"
+  fi
+}
+
+install_windsurf() {
+  mkdir -p ".windsurf/rules"
+  curl -fsSL "${REPO_URL}/windsurf/tollgate.md" -o ".windsurf/rules/tollgate.md"
+  echo "Windsurf: rule installed at .windsurf/rules/tollgate.md"
+}
+
+install_codex() {
+  if [ -f "AGENTS.md" ]; then
+    echo "" >> "AGENTS.md"
+    curl -fsSL "${REPO_URL}/codex/AGENTS.md" >> "AGENTS.md"
+    echo "Codex: appended to AGENTS.md"
+  else
+    curl -fsSL "${REPO_URL}/codex/AGENTS.md" -o "AGENTS.md"
+    echo "Codex: AGENTS.md created"
+  fi
+}
+
+case "$TOOL" in
+  claude)   install_claude_code ;;
+  cursor)   install_cursor ;;
+  copilot)  install_copilot ;;
+  windsurf) install_windsurf ;;
+  codex)    install_codex ;;
+  all)
+    install_claude_code
+    install_cursor
+    install_copilot
+    install_windsurf
+    install_codex
+    ;;
+  *)
+    echo "Tollgate skill installer"
+    echo ""
+    echo "Usage:"
+    echo "  bash install.sh --tool claude     # Claude Code (~/.claude/skills/tollgate/)"
+    echo "  bash install.sh --tool cursor     # Cursor (.cursor/rules/tollgate.mdc)"
+    echo "  bash install.sh --tool copilot    # GitHub Copilot (.github/copilot-instructions.md)"
+    echo "  bash install.sh --tool windsurf   # Windsurf (.windsurf/rules/tollgate.md)"
+    echo "  bash install.sh --tool codex      # Codex (AGENTS.md)"
+    echo "  bash install.sh --tool all        # All of the above"
+    echo ""
+    echo "Or install for Claude Code (most common):"
+    install_claude_code
+    ;;
+esac

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "tollgate-skill",
+  "version": "1.0.0",
+  "description": "AI coding tool instructions for Tollgate — real-time gross-margin observability for AI agents",
+  "bin": {
+    "tollgate-skill": "./bin/tollgate-skill.js"
+  },
+  "files": [
+    "bin/",
+    "claude-code/",
+    "cursor/",
+    "copilot/",
+    "windsurf/",
+    "codex/",
+    "install.sh",
+    ".claude-plugin/"
+  ],
+  "keywords": [
+    "tollgate",
+    "llm",
+    "ai",
+    "cost",
+    "margin",
+    "observability",
+    "claude",
+    "cursor",
+    "copilot",
+    "windsurf",
+    "codex",
+    "agents"
+  ],
+  "author": "Tollgate <hello@tollgateai.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/Tollgateai/tollgate-skill",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Tollgateai/tollgate-skill.git"
+  },
+  "engines": {
+    "node": ">=16"
+  }
+}

package/windsurf/tollgate.md

@@ -0,0 +1,123 @@
+# Tollgate Integration
+
+When the user asks to integrate Tollgate, add LLM cost tracking, or set up gross-margin observability, follow these instructions.
+
+Tollgate wraps your LLM provider client and tracks every API call — attributing cost to a customer and run, then joining it with revenue to show real-time gross margin per customer.
+
+## Setup
+
+Add to environment:
+```
+TOLLGATE_API_KEY=tg_live_your_key_here
+```
+
+Install:
+```bash
+npm install @tollgateai/sdk    # TypeScript
+pip install tollgateai          # Python
+```
+
+## Wrap the provider (TypeScript)
+
+Anthropic:
+```typescript
+import Anthropic from '@anthropic-ai/sdk';
+import { createTollgateClient, wrapAnthropic } from '@tollgateai/sdk';
+
+const tollgate = createTollgateClient();
+const anthropic = wrapAnthropic(new Anthropic(), tollgate, {
+  customerId: 'cust_acme',
+  runId: 'ticket_8842',
+});
+```
+
+OpenAI:
+```typescript
+import OpenAI from 'openai';
+import { createTollgateClient, wrapOpenAI } from '@tollgateai/sdk';
+
+const tollgate = createTollgateClient();
+const openai = wrapOpenAI(new OpenAI(), tollgate, { customerId: 'cust_acme', runId: 'ticket_8842' });
+```
+
+OpenAI-compatible (Groq, OpenRouter, vLLM, Together):
+```typescript
+const client = wrapOpenAI(
+  new OpenAI({ baseURL: 'https://api.groq.com/openai/v1', apiKey: process.env.GROQ_API_KEY }),
+  tollgate,
+  { customerId: 'cust_acme', runId: 'ticket_8842', provider: 'openai_compatible' },
+);
+```
+
+Google Gemini:
+```typescript
+import { GoogleGenAI } from '@google/genai';
+import { createTollgateClient, wrapGemini } from '@tollgateai/sdk';
+const gemini = wrapGemini(new GoogleGenAI({ apiKey: process.env.GOOGLE_API_KEY }), tollgate, { customerId: 'cust_acme', runId: 'ticket_8842' });
+```
+
+AWS Bedrock:
+```typescript
+import { BedrockRuntimeClient } from '@aws-sdk/client-bedrock-runtime';
+import { createTollgateClient, wrapBedrock } from '@tollgateai/sdk';
+const bedrock = wrapBedrock(new BedrockRuntimeClient({ region: 'us-east-1' }), tollgate, { customerId: 'cust_acme', runId: 'ticket_8842' });
+```
+
+## Wrap the provider (Python)
+
+```python
+from tollgate import create_tollgate_client, wrap_anthropic, wrap_openai
+
+tollgate = create_tollgate_client()
+
+import anthropic
+client = wrap_anthropic(anthropic.Anthropic(), tollgate, customer_id="cust_acme", run_id="ticket_8842")
+
+from openai import OpenAI
+client = wrap_openai(OpenAI(), tollgate, customer_id="cust_acme", run_id="ticket_8842")
+```
+
+## OpenAI streaming
+
+Add stream_options or token counts won't be captured:
+```typescript
+const stream = await openai.chat.completions.create({
+  model: 'gpt-4o',
+  messages: [...],
+  stream: true,
+  stream_options: { include_usage: true },
+});
+```
+
+## Close a multi-step run
+
+```typescript
+await tollgate.resolve({
+  runId: 'ticket_8842',
+  customerId: 'cust_acme',
+  outcome: 'resolved',     // 'resolved' | 'escalated' | 'failed'
+  revenueUnitCents: 50,
+});
+```
+
+## Rules
+
+- idempotencyKey must be unique per event — use runId#step_N pattern
+- Never send prompt content (messages, content, input, output fields are rejected)
+- reasoningTokens bills at output rate — pass separately
+- cachedTokens bills at reduced rate — pass separately
+- outcome only on the closing event of a run
+
+## Direct REST API
+
+```
+POST https://tollgateai.dev/api/track
+Authorization: Bearer tg_live_…
+Content-Type: application/json
+
+{ "customerId": "cust_acme", "runId": "ticket_8842", "provider": "anthropic",
+  "model": "claude-opus-4-8", "tokensIn": 1200, "tokensOut": 340,
+  "idempotencyKey": "ticket_8842#step_1" }
+```
+
+Full docs: https://www.tollgateai.dev/docs