canary-agent 0.1.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,139 @@
+# canary-agent
+
+API observability SDK for AI agents. Zero-dependency Node.js library that captures HTTP telemetry and structured feedback from AI agent sessions.
+
+## Install
+
+```bash
+npm install canary-agent
+```
+
+## Quick Start
+
+### As MCP Server (recommended for Claude Code / Cursor)
+
+Add to your project's `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "canary-journal": {
+      "command": "npx",
+      "args": ["-y", "canary-agent"],
+      "env": {
+        "CANARY_API_KEY": "your_api_key",
+        "CANARY_ENDPOINT": "https://api.canary.dev"
+      }
+    }
+  }
+}
+```
+
+The MCP server provides two tools:
+
+- **`canary_annotate`** — Record API observations during your work
+- **`canary_report`** — Submit structured feedback when your task is complete
+
+### As SDK (programmatic)
+
+```typescript
+import { init, shutdown, survey } from 'canary-agent';
+
+// Initialize — patches http/https and fetch automatically
+init({
+  apiKey: process.env.CANARY_API_KEY,
+  endpoint: 'https://api.canary.dev',
+});
+
+// All HTTP calls to tracked APIs are now captured automatically
+const res = await fetch('https://api.stripe.com/v1/charges');
+
+// Optional: submit manual feedback
+survey({
+  worked: true,
+  context: 'Payment processed successfully',
+  provider: 'stripe',
+});
+
+// At shutdown, auto-reports are generated
+await shutdown();
+```
+
+## Configuration
+
+| Option | Env Var | Description |
+|--------|---------|-------------|
+| `apiKey` | `CANARY_API_KEY` | Your Canary API key (required, starts with `cnry_sk_`) |
+| `endpoint` | `CANARY_ENDPOINT` | Backend URL (default: `https://api.canary.dev`) |
+| `sessionId` | `CANARY_SESSION_ID` | Link to a specific session |
+| `agentName` | `CANARY_AGENT_NAME` | Identify this agent in multi-agent setups |
+| `autoReport` | — | Auto-generate feedback at shutdown (default: `true`) |
+| `autoFlush` | — | Start periodic flush timer (default: `true`) |
+
+## Session Correlation
+
+Use `runWithSession()` to scope API calls to a session:
+
+```typescript
+import { runWithSession } from 'canary-agent';
+
+await runWithSession('skill-execution-42', async () => {
+  // All API calls here are grouped under one session
+  await fetch('https://api.stripe.com/v1/charges', { ... });
+});
+```
+
+## MCP Server CLI
+
+```bash
+npx canary-agent --api-key=YOUR_KEY --endpoint=https://api.canary.dev
+```
+
+Or with environment variables:
+
+```bash
+CANARY_API_KEY=your_key npx canary-agent
+```
+
+## Multi-Agent Setup
+
+Set `CANARY_AGENT_NAME` to identify each agent under a shared API key:
+
+```json
+{
+  "mcpServers": {
+    "canary-journal": {
+      "command": "npx",
+      "args": ["-y", "canary-agent"],
+      "env": {
+        "CANARY_API_KEY": "shared_team_key",
+        "CANARY_AGENT_NAME": "checkout-agent"
+      }
+    }
+  }
+}
+```
+
+## OpenClaw Integration
+
+For OpenClaw skills, import the auto-init module:
+
+```typescript
+import 'canary-agent/openclaw';
+```
+
+This automatically initializes Canary when `OPENCLAW_SESSION_ID` and `CANARY_API_KEY` are set.
+
+## Tracked Providers
+
+**AI/ML:** OpenAI, Anthropic, Cohere, Google AI, Replicate, Hugging Face, Mistral
+**Payments:** Stripe, Square, PayPal, Braintree
+**Communication:** Twilio, SendGrid, Mailgun, Postmark, Resend
+**Developer:** GitHub, GitLab, Slack, Discord, Linear
+**Cloud:** Cloudflare, Vercel, Heroku, Netlify
+**Data:** Segment, Mixpanel, Amplitude
+**SaaS:** Notion, Airtable, HubSpot, Salesforce, and more
+
+## License
+
+MIT