watchmyagents 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MinedorFBM and Watch My Agents contributors
+
+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,183 @@
+# Watch My Agents
+
+**Security observability for AI agents.** A zero-dependency CLI + SDK that captures every action your AI agents take — tool calls, prompts, state transitions, errors, multi-agent comms — into local NDJSON logs. Built for security audits, not just token counting.
+
+Designed around three guarantees:
+
+1. **Local-first.** Raw payloads (prompts, outputs, tool arguments) stay 100% on your machine. Nothing leaves unless you explicitly opt in.
+2. **Trace everything, not just what costs tokens.** A `web_fetch` to a suspicious URL carries zero tokens but is exactly what a security audit needs to see.
+3. **Zero dependencies.** Only Node.js 18+ built-ins. No telemetry, no phone-home, no hidden network calls.
+
+---
+
+## Install
+
+```bash
+npm install -g watchmyagents
+```
+
+## Quickstart — monitor an Anthropic Managed Agent
+
+You'll need:
+- An Anthropic API key (`sk-ant-…`)
+- The `agent_id` of the agent you want to monitor (from [console.anthropic.com](https://console.anthropic.com))
+
+```bash
+export ANTHROPIC_API_KEY="sk-ant-..."
+
+wma-fetch --agent-id agent_01XaN... --since 1h
+wma-inspect
+```
+
+That's it. You'll see a security-focused summary of everything the agent did:
+
+```
+━━━ WatchMyAgents log inspector ━━━
+entries          : 90
+sessions         : 2 (session_end entries: 2)
+model            : claude-sonnet-4-6
+window           : 2026-05-23T05:32:08Z → 2026-05-23T06:12:40Z
+status           : ok=90  error=0
+
+── Tokens ──
+total            : 811,798  (in=26 out=22,996 cache_r=492,220 cache_w=296,556)
+
+── By tool ──
+  web_search                               calls=  20  tokens=       0
+  web_fetch                                calls=   2  tokens=       0
+
+── By action_type ──
+  llm_call                                 calls=  12  tokens=  811798
+  state_transition                         calls=  28
+  user_message                             calls=   7
+  thinking                                 calls=   9
+  message                                  calls=  10
+  tool_use                                 calls=  22
+
+── Top destinations (tool inputs) ──
+    1×  web_search       "AI agent security attack vectors prompt injection..."
+    1×  web_fetch        https://genai.owasp.org/2025/12/09/owasp-genai-...
+
+── Action sequences (top transitions) ──
+   19×  22.1%  state_transition → state_transition
+   17×  19.8%  tool_use → tool_use
+   ...
+
+── Tool latency ──
+  web_search           n= 20  p50=3,744 ms  p95=4,009 ms  max=4,009 ms
+  web_fetch            n=  2  p50=1,477 ms  p95=1,477 ms
+
+── Rate metrics ──
+  tokens/min       : 721
+  calls/min        : 0.08
+```
+
+## What gets logged
+
+Each line of the NDJSON file is one agent action. The 18 `action_type` values captured today:
+
+| `action_type` | When emitted |
+|---|---|
+| `user_message` | A prompt is sent to the agent |
+| `user_interrupt` | Manual mid-execution stop |
+| `tool_confirmation` | Approve / deny a tool call gated by a permission policy |
+| `custom_tool_result` | Orchestrator returns a custom tool result |
+| `message` | Agent text response |
+| `thinking` | Agent reasoning block |
+| `llm_call` | Model inference call (with token usage) |
+| `tool_use` | Pre-built agent tool invoked (web_search, web_fetch, bash, …) |
+| `mcp_tool_use` | MCP server tool invoked |
+| `custom_tool_use` | Custom tool defined by the orchestrator |
+| `context_compacted` | Context window saturated — history compacted |
+| `thread_created` | A multi-agent thread was created |
+| `thread_message_sent` / `_received` | Inter-agent communication in multi-agent sessions |
+| `config_change` | Session config (system prompt, tools, …) was updated mid-flight ⚠️ |
+| `state_transition` | Session/thread `running`/`idle`/`rescheduled`/`terminated` |
+| `session_error` | Error during session processing |
+| `session_end` | Synthetic marker at end of each fetch (tokens summary) |
+
+Each entry carries: `id`, `agent_id`, `framework`, `timestamp`, `action_type`, `tool_name`, `model`, `duration_ms`, `tokens_used`, `input_tokens`, `output_tokens`, `cache_read_tokens`, `cache_creation_tokens`, `status`, `error`, `sequence_number`, `session_id`, `input`, `output`.
+
+**The `input` and `output` fields contain the raw payload** (tool arguments, agent responses, queries). They never leave your machine.
+
+## CLI reference
+
+### `wma-fetch` — pull events from Anthropic Managed Agents
+
+```bash
+wma-fetch --agent-id <agent_id> [--session-id <sess_id>] [--since 1h]
+         [--log-dir ./watchmyagents-logs] [--dump-raw]
+```
+
+| Flag | Effect |
+|---|---|
+| `--agent-id agent_xxx` | Required — Anthropic agent identifier |
+| `--since 1h` / `24h` / `7d` | Fetch window (default: all) |
+| `--session-id sesn_xxx` | Limit to a single session |
+| `--log-dir ./logs` | Where to write NDJSON (default `./watchmyagents-logs`) |
+| `--dump-raw` | Also save raw API events alongside (forensic / debugging) |
+| `--api-key sk-ant-…` | Override the `ANTHROPIC_API_KEY` env var |
+
+Logs land in `./watchmyagents-logs/<agent_id>/<date>.ndjson` (file mode `0600`, dir `0700`).
+
+### `wma-inspect` — audit the logs
+
+```bash
+wma-inspect [path]
+```
+
+`path` can be a single `.ndjson` file or a directory (default: `./watchmyagents-logs`).
+
+Outputs sections aligned with security audit needs: tokens summary, by-tool / by-action-type breakdowns, top tool destinations (URLs / queries), action-sequence transitions, tool error rates, p50/p95/max latency per tool, rate metrics.
+
+## Automating (cron)
+
+For continuous monitoring, run `wma-fetch` on a cron:
+
+```cron
+# Every 15 minutes
+*/15 * * * * cd /path/to/project && wma-fetch --agent-id agent_01XaN... --since 20m
+```
+
+Or for daily reports:
+
+```cron
+# Once per night, fetch the full last 24h
+5 0 * * * cd /path/to/project && wma-fetch --agent-id agent_01XaN... --since 25h
+```
+
+## Data sovereignty model
+
+WatchMyAgents is built so that **your prompts and outputs never have to leave your machine**:
+
+| Where | What lives there |
+|---|---|
+| **Your machine** (`./watchmyagents-logs/`) | Full NDJSON with all prompts, tool inputs, agent outputs. `chmod 600` on every file. |
+| **Anthropic API** | Where the agent runs. WMA pulls events via the public REST API only. |
+| **WMA infrastructure** | **Nothing today.** Future opt-in telemetry will ship only anonymized metadata (counts, timings, hashes) — never raw payloads. |
+
+This is the "local-first" guarantee. It is the product, not a marketing claim.
+
+## Security
+
+WMA requires your Anthropic API key to call the Managed Agents REST API on your behalf. The key:
+
+- Is read from the `ANTHROPIC_API_KEY` env var or the `--api-key` flag
+- Is **never** written to disk, **never** logged, **never** transmitted anywhere except `api.anthropic.com` over HTTPS
+- Is only ever held in process memory for the duration of a `wma-fetch` run
+
+For added safety, generate a **workspace-scoped** API key with read-only permissions on the agents you want to monitor: [console.anthropic.com → API Keys](https://console.anthropic.com/settings/keys).
+
+Report vulnerabilities via [SECURITY.md](./SECURITY.md).
+
+## Status
+
+- ✅ Anthropic Managed Agents (post-hoc fetch + audit)
+- 🚧 Encrypted upload to customer's own cloud (S3/GCS/Azure with `age` public-key encryption)
+- 🚧 Anonymized telemetry to WMA cloud (opt-in, freemium model)
+- 🚧 Shield product — real-time policy gating via `user.tool_confirmation` + `user.interrupt`
+- 🚧 Adapters for in-process agents (Claude SDK, OpenAI, LangChain, generic) — code present in `src/adapters/` but unverified against the new Modèle C architecture; documentation will follow once re-validated
+
+## License
+
+[MIT](./LICENSE)

package/SECURITY.md

@@ -0,0 +1,78 @@
+# Security Policy
+
+## How Watch My Agents handles your secrets
+
+WMA is designed so that **your data and credentials stay on your machine**. This document describes how, and where the trust boundaries lie.
+
+### Your Anthropic API key
+
+WMA needs your Anthropic API key to call the Managed Agents REST API on your behalf.
+
+| Property | Behavior |
+|---|---|
+| **Source** | Environment variable `ANTHROPIC_API_KEY` or `--api-key` CLI flag |
+| **Storage** | Held in process memory for the duration of a `wma-fetch` run. Never persisted to disk by WMA. |
+| **Network** | Sent only to `api.anthropic.com` over HTTPS with strict certificate verification (`rejectUnauthorized: true`) |
+| **Logging** | The key is never written to NDJSON logs, never printed in error messages, never included in any export |
+| **Telemetry** | WMA performs zero telemetry today. No phone-home, no usage reporting. |
+
+**Recommendation:** generate a workspace-scoped API key with read-only permissions on the agents you want to monitor. See [Anthropic Console → API Keys](https://console.anthropic.com/settings/keys).
+
+### Local log files
+
+`wma-fetch` writes NDJSON files to `./watchmyagents-logs/<agent_id>/<date>.ndjson` with the following protections:
+
+- Directory mode: `0700` (only your user can read/list)
+- File mode: `0600` (only your user can read/write)
+- No encryption at rest by default — files are plaintext JSON Lines on disk
+
+**Add `watchmyagents-logs/` to your `.gitignore`** to avoid committing prompts and tool outputs to a repo.
+
+### What WMA does NOT do
+
+- ❌ Does not phone home, telemetry, analytics, or usage reporting
+- ❌ Does not send any data to WMA-controlled servers
+- ❌ Does not store, log, or transmit your Anthropic API key anywhere except `api.anthropic.com`
+- ❌ Does not require an account, signup, or license key
+
+## Threat model
+
+WMA is built to give visibility into your AI agent's behavior. It is **observational**, not preventive.
+
+### What WMA defends against
+
+- **Blind spots in agent behavior.** Tool calls, prompts, state transitions, errors are all captured for after-the-fact analysis.
+- **Token-only observability tools.** WMA captures every action including zero-token ones (`tool_use`, `state_transition`, etc.) that are the most security-relevant.
+- **Vendor lock-in.** NDJSON is portable; you own the data.
+
+### What WMA does NOT defend against
+
+- **Real-time attack prevention.** WMA observes after events occur. For inline policy gating, see the upcoming Shield product.
+- **A compromised host.** If an attacker has read access to your user account, they can read the log files. Consider encryption at rest (filesystem-level, or future opt-in via `age`) for sensitive environments.
+- **Tampering with local logs.** Files are append-only by convention, not enforced. A future release will add a per-line hash chain for tamper-evident audit.
+- **A compromised Anthropic API.** WMA trusts the events delivered by Anthropic. This is out of scope.
+
+## Supply chain
+
+- All code is open source on [GitHub](https://github.com/minedorfbm/watchmyagents)
+- Zero runtime dependencies (uses Node.js 18+ built-ins only)
+- One dev dependency (`@anthropic-ai/sdk`) for the optional adapter examples
+- Future releases will use `npm publish --provenance` for SLSA build attestation
+
+## Reporting a vulnerability
+
+If you discover a security issue, **please do NOT open a public GitHub issue.**
+
+Email: [minedor@watchmyagents.com](mailto:minedor@watchmyagents.com)
+
+Include:
+- A description of the issue and its impact
+- Steps to reproduce
+- The version of WMA affected (`npm list -g watchmyagents`)
+- Your suggested fix, if any
+
+We aim to acknowledge reports within 72 hours and provide an initial assessment within 7 days. Coordinated disclosure preferred.
+
+## Updates
+
+This policy may be updated as the product evolves (notably when Shield, encrypted exports, and anonymized telemetry ship). Watch the repository for changes.

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "watchmyagents",
+  "version": "0.1.0",
+  "description": "Security observability for AI agents — local-first NDJSON capture of every agent action (tool calls, prompts, state transitions, errors). Built for security audits, not just token counting.",
+  "type": "module",
+  "main": "./src/index.cjs",
+  "module": "./src/index.js",
+  "exports": {
+    ".": {
+      "import": "./src/index.js",
+      "require": "./src/index.cjs"
+    },
+    "./adapters/claude": "./src/adapters/claude.js",
+    "./adapters/openai": "./src/adapters/openai.js",
+    "./adapters/langchain": "./src/adapters/langchain.js",
+    "./adapters/generic": "./src/adapters/generic.js"
+  },
+  "files": [
+    "src/",
+    "scripts/inspect.js",
+    "scripts/fetch-anthropic.js",
+    "README.md",
+    "SECURITY.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "wma-inspect": "scripts/inspect.js",
+    "wma-fetch": "scripts/fetch-anthropic.js"
+  },
+  "scripts": {
+    "inspect": "node scripts/inspect.js",
+    "fetch": "node scripts/fetch-anthropic.js",
+    "example": "node examples/claude-agent/index.js"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@anthropic-ai/sdk": "latest"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "monitoring",
+    "logging",
+    "security",
+    "observability",
+    "cybersecurity",
+    "anthropic",
+    "claude",
+    "managed-agents",
+    "audit",
+    "ndjson"
+  ],
+  "author": "MinedorFBM <minedor@watchmyagents.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/minedorfbm/watchmyagents.git"
+  },
+  "homepage": "https://github.com/minedorfbm/watchmyagents#readme",
+  "bugs": {
+    "url": "https://github.com/minedorfbm/watchmyagents/issues"
+  }
+}

package/scripts/fetch-anthropic.js

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+// wma-fetch — pull session events from Anthropic Managed Agents and
+// write them as WatchMyAgents NDJSON, ready for `wma-inspect`.
+//
+// Usage:
+//   wma-fetch --agent-id agent_xxx [--session-id sess_xxx] [--since 1h]
+//             [--log-dir ./watchmyagents-logs] [--dump-raw]
+//
+// API key is read from --api-key or env ANTHROPIC_API_KEY.
+
+import { mkdir, appendFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { Logger } from '../src/logger.js';
+import { TokenTracker } from '../src/tokens.js';
+import {
+  getAgent, listSessions, fetchSessionEntries, fetchRawEvents,
+} from '../src/sources/anthropic-managed.js';
+
+function parseArgs(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--')) {
+      const k = a.slice(2);
+      const n = argv[i + 1];
+      if (n == null || n.startsWith('--')) out[k] = true;
+      else { out[k] = n; i++; }
+    }
+  }
+  return out;
+}
+
+function parseSince(s) {
+  if (!s || s === true) return null;
+  const m = String(s).match(/^(\d+)\s*([smhd])$/);
+  if (m) {
+    const n = parseInt(m[1], 10);
+    const mult = { s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 }[m[2]];
+    return new Date(Date.now() - n * mult);
+  }
+  const d = new Date(s);
+  if (isNaN(d)) throw new Error(`invalid --since value: ${s}`);
+  return d;
+}
+
+function die(msg, code = 1) { process.stderr.write(`${msg}\n`); process.exit(code); }
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const apiKey = args['api-key'] || process.env.ANTHROPIC_API_KEY;
+  const agentId = args['agent-id'];
+  const sessionId = args['session-id'];
+  const since = args.since ? parseSince(args.since) : null;
+  const logDir = resolve(args['log-dir'] || './watchmyagents-logs');
+  const dumpRaw = !!args['dump-raw'];
+
+  if (!apiKey) die('error: --api-key or ANTHROPIC_API_KEY required');
+  if (!agentId) die('error: --agent-id required (e.g. agent_01XaNB4M88ZvcW8FoQ5GC14A)');
+
+  process.stdout.write(`[wma-fetch] resolving agent ${agentId}…\n`);
+  const agent = await getAgent(apiKey, agentId).catch(e => die(`failed to GET agent: ${e.message}`));
+  const rawModel = agent.model || agent.config?.model || null;
+  // API may return model as { id, speed } object or as a plain string.
+  const model = (rawModel && typeof rawModel === 'object') ? (rawModel.id || null) : rawModel;
+  process.stdout.write(`[wma-fetch] model: ${model || '(unknown)'}\n`);
+
+  let sessions;
+  if (sessionId) {
+    sessions = [{ id: sessionId, created_at: new Date().toISOString() }];
+  } else {
+    process.stdout.write(`[wma-fetch] listing sessions${since ? ` since ${since.toISOString()}` : ''}…\n`);
+    sessions = await listSessions(apiKey, { agentId, since })
+      .catch(e => die(`failed to list sessions: ${e.message}`));
+  }
+
+  if (sessions.length === 0) {
+    process.stdout.write('[wma-fetch] no sessions to fetch\n');
+    return;
+  }
+  process.stdout.write(`[wma-fetch] ${sessions.length} session(s) to fetch\n`);
+
+  let totalEntries = 0;
+  for (const s of sessions) {
+    const sid = s.id;
+    process.stdout.write(`\n[wma-fetch] session ${sid}\n`);
+
+    if (dumpRaw) {
+      const rawPath = join(logDir, agentId, `raw-${sid}.jsonl`);
+      await mkdir(join(logDir, agentId), { recursive: true, mode: 0o700 });
+      for await (const ev of fetchRawEvents(apiKey, sid)) {
+        await appendFile(rawPath, JSON.stringify(ev) + '\n', { encoding: 'utf8', mode: 0o600 });
+      }
+      process.stdout.write(`  raw events  → ${rawPath}\n`);
+    }
+
+    const logger = new Logger({ logDir, agentId, sessionId: sid, silent: true });
+    const tracker = new TokenTracker();
+
+    let count = 0;
+    for await (const entry of fetchSessionEntries({ apiKey, agentId, sessionId: sid, model })) {
+      const written = await logger.write(entry);
+      tracker.record(written);
+      count++;
+    }
+
+    const stats = tracker.stats().total;
+    const sessionEnd = await logger.write({
+      action_type: 'session_end',
+      framework: 'anthropic-managed',
+      status: 'ok',
+      model,
+      session_tokens: {
+        input: stats.input, output: stats.output,
+        cache_read: stats.cache_read, cache_creation: stats.cache_creation,
+        total: stats.sum,
+      },
+      session_cost_usd: stats.cost_usd || null,
+    });
+
+    process.stdout.write(`  entries     : ${count} (+1 session_end)\n`);
+    process.stdout.write(`  tokens      : in=${stats.input} out=${stats.output} cache_r=${stats.cache_read} cache_w=${stats.cache_creation}\n`);
+    process.stdout.write(`  written to  : ${logger._pathForToday()}\n`);
+    totalEntries += count + 1;
+  }
+
+  process.stdout.write(`\n[wma-fetch] done — ${totalEntries} total entries across ${sessions.length} session(s)\n`);
+  process.stdout.write(`[wma-fetch] inspect with: npx wma-inspect ${logDir}\n`);
+}
+
+main().catch(e => { process.stderr.write(`error: ${e.stack || e.message}\n`); process.exit(1); });