@slashfi/agents-sdk 0.61.0 → 0.62.0

package/README.md

@@ -1,244 +1,335 @@
 # Agents SDK
 
-SDK for building, testing, and publishing AI agent definitions. Includes the `adk` CLI (Agent Development Kit) for working with MCP servers and the `@agentdef` npm package ecosystem.
+SDK for building, connecting, and using AI agents. Includes the `adk` CLI for managing agent connections, installing skills for coding agents, and working with MCP servers.
 
-## Installation
+## Copy this into your coding agent
+
+```
+Help me install the Agent Development Kit (adk) — a CLI that connects coding agents to remote
+APIs and MCPs. It also installs skill files so you know how to use them.
+
+Run this to install it:
+curl -fsSL https://registry.slash.com/adk/install | sh
+
+Then follow the printed instructions to set up skills and connect to agents.
+```
+
+---
+
+## Quick Start
 
 ```bash
-bun add @slashfi/agents-sdk
-# or
-npm install @slashfi/agents-sdk
+# Install via curl
+curl -fsSL https://registry.slash.com/adk/install | sh
+
+# Or via npm
+npm install -g @slashfi/agents-sdk
 ```
 
-## Overview
+```bash
+# Set up skills for your coding agent (Claude Code, Cursor, Copilot, etc.)
+adk init
+
+# Connect to an agent from the public registry
+adk ref add notion
 
-The SDK has two main parts:
+# Browse available agents
+adk registry browse public
 
-1. **Runtime** — define agents, tools, registries, and servers programmatically
-2. **ADK CLI** — introspect MCP servers, pack agent definitions, publish to npm
+# Call a tool
+adk ref call notion notion-search '{"query": "hello"}'
+```
 
 ---
 
 ## ADK CLI
 
-The Agent Development Kit CLI. One tool for the full agent definition lifecycle.
+The Agent Development Kit CLI. One tool for connecting to agents, managing skills, and the full agent definition lifecycle.
 
 ```bash
 adk --help
 ```
 
-### Commands
+### Commands Overview
 
 | Command | Description |
 |---------|-------------|
-| `adk introspect` | Connect to an MCP server → produce `agent.json` |
-| `adk pack` | Generate a publishable `@agentdef/*` npm package from `agent.json` |
-| `adk publish` | Pack + `npm publish` in one step |
-| `adk codegen` | Full codegen from MCP server (TypeScript types, CLI, manifest) |
-| `adk use` | Execute a tool on a generated agent |
-| `adk list` | List all generated agents |
+| `adk init` | Set up skills for coding agents (Claude, Cursor, Copilot, Codex, Windsurf, Hermes) |
+| `adk ref add <name>` | Install an agent from a registry |
+| `adk ref call <name> <tool>` | Call a tool on a connected agent |
+| `adk ref auth <name>` | Authenticate to a service |
+| `adk ref inspect <name>` | See available tools and resources |
+| `adk registry browse <name>` | Browse agents on a registry |
+
+---
+
+## Working with Agents
 
-### Workflow
+### Setting Up Skills
+
+`adk init` installs skill files for your coding agents. It auto-detects which agents you have installed and writes skill files in the standard YAML-frontmatter markdown format from [agentskills.io](https://agentskills.io).
 
 ```bash
-# 1. Introspect any MCP server → agent.json
-adk introspect --server 'npx @notionhq/notion-mcp-server' --name notion
-
-# 2. Review the generated agent.json (supports JSONC — comments allowed)
-cat agent.json
-
-# 3. Pack into a publishable npm package
-adk pack
-# ✅ Packed @agentdef/notion@1.0.0
-#    Hash: ba845dfb
-#    Tools: 22
-#    Size: 28.7KB
-
-# 4. Publish to npm
-adk publish
-# ✅ Published @agentdef/notion@1.0.0
+# Auto-detect and set up all detected agents
+adk init
+
+# Target specific agents
+adk init --target claude --target cursor --target codex
+
+# Custom output path
+adk init --target claude:./my-skills
 ```
 
-### `adk introspect`
+Supported agents:
+
+| Preset | Default Path | Format |
+|--------|-------------|--------|
+| `claude` | `~/.claude/skills` | SKILL.md |
+| `cursor` | `.cursor/rules` | SKILL.md |
+| `copilot` | `.github` | SKILL.md |
+| `windsurf` | `.` | SKILL.md |
+| `codex` | `.` | SKILL.md |
+| `hermes` | `~/.hermes/skills` | SKILL.md |
+
+### Connecting to Agents
 
-Connects to an MCP server via stdio, discovers all tools, deduplicates shared `$defs`, and writes a `SerializedAgentDefinition` as JSON.
+Install agents from a registry. The public registry at `registry.slash.com` is configured by default.
 
 ```bash
-adk introspect --server 'npx @notionhq/notion-mcp-server' --name notion
-adk introspect --server 'npx @modelcontextprotocol/server-github' --name github --out ./definitions/github.json
+# Install from the public registry (default)
+adk ref add notion
+adk ref add linear
+adk ref add github
+
+# Install from a specific registry
+adk ref add myagent --registry internal
+
+# Install from a direct URL
+adk ref add myapi --url https://api.example.com/mcp
 ```
 
-**Options:**
+When you install a ref, the CLI:
+1. Resolves the agent from the registry
+2. Materializes tool schemas locally (`~/.adk/refs/<name>/tools/`)
+3. Downloads skill files (`~/.adk/refs/<name>/skills/`)
+4. Generates TypeScript types (`~/.adk/refs/<name>/types/`)
 
-| Flag | Description | Default |
-|------|-------------|---------|
-| `--server <cmd>` | MCP server command to run | required |
-| `--name <name>` | Agent name | required |
-| `--out <path>` | Output file path | `./<name>.json` |
+### Authentication
 
-### `adk pack`
+```bash
+# Authenticate to a service (opens browser for OAuth, or prompts for API key)
+adk ref auth notion
 
-Reads `agent.json` and generates a complete, publishable npm package:
+# Check auth status
+adk ref auth-status notion
 
-```
-@agentdef/notion/
-├── package.json       ← generated from agent.json
-├── agent.json         ← full SerializedAgentDefinition
-├── meta.json          ← version metadata + diff from previous
-├── index.js           ← re-export for ESM import
-└── index.d.ts         ← typed as SerializedAgentDefinition
+# Provide an API key directly
+adk ref auth myapi --api-key sk-...
 ```
 
-**Options:**
+### Using Agents
 
-| Flag | Description | Default |
-|------|-------------|---------|
-| `--agent <path>` | Path to agent.json | `./agent.json` |
-| `--out <dir>` | Output directory | `./dist` |
-| `--scope <scope>` | npm scope | `@agentdef` |
-| `--previous <path>` | Previous agent.json for version diff | — |
+```bash
+# Call a tool
+adk ref call notion notion-search '{"query": "meeting notes"}'
 
-**Version diff** — pass `--previous` to generate a diff in `meta.json`:
+# Inspect available tools
+adk ref inspect notion
+adk ref inspect notion --full  # Include full input schemas
 
-```bash
-adk pack --previous ./agent-v1.json
-# ✅ Packed @agentdef/notion@1.1.0
-#    Added: new-tool
-#    Removed: deprecated-tool
-#    Modified: search (inputSchema changed)
-```
+# List resources
+adk ref resources notion
 
-### `adk publish`
+# Read a resource
+adk ref read notion resource://docs/readme
 
-Packs + publishes to npm. Includes safety checks:
+# List all connected agents
+adk ref list
+```
 
-- **Duplicate version** — refuses with clear error + hint
-- **Out-of-order version** — refuses to clobber `latest` tag
-- **Auth failures** — hints to `npm login` or set `NPM_TOKEN`
+### Managing Registries
 
 ```bash
-adk publish
-adk publish --dry-run
-adk publish --tag beta
-adk publish --registry http://localhost:4873
-```
+# Add a registry
+adk registry add https://registry.slash.com --name public
 
-**Options:**
+# Browse available agents
+adk registry browse public
+adk registry browse public --query "database"
 
-| Flag | Description | Default |
-|------|-------------|---------|
-| `--dry-run` | Pack without publishing | — |
-| `--tag <tag>` | npm dist-tag | `latest` |
-| `--access <level>` | `public` or `restricted` | `public` |
-| `--registry <url>` | npm registry URL | default npm |
-| + all `pack` options | | |
+# Inspect registry details
+adk registry inspect public
 
-**Error examples:**
+# Test connectivity
+adk registry test
 
+# List configured registries
+adk registry list
 ```
-✗ @agentdef/notion@1.0.0 already exists in registry
 
-  Published versions: 1.0.0
-  Hint: bump the version in agent.json, or use --tag to publish a pre-release
-  Debug: cat /home/user/.npm/_logs/2026-03-29_debug.log | tail -40
+---
+
+## Configuration
+
+### consumer-config.json
+
+All state lives in `~/.adk/consumer-config.json`. This is the "package.json" of the agent world — registries are like npm registries, refs are like dependencies.
+
+```jsonc
+{
+  "registries": [
+    { "url": "https://registry.slash.com", "name": "public", "status": "active" }
+  ],
+  "refs": [
+    {
+      "ref": "notion",
+      "scheme": "registry",
+      "sourceRegistry": { "url": "https://registry.slash.com", "agentPath": "notion" },
+      "config": {
+        "access_token": "secret:v1:aes-256-gcm:base64encodedciphertext..."
+      }
+    }
+  ]
+}
 ```
 
+Config values prefixed with `secret:` are encrypted. Plain values are stored as-is.
+
+### Encrypted Secrets
+
+Secrets (OAuth tokens, API keys) are encrypted with AES-256-GCM before being stored in `consumer-config.json`. The encryption key lives at `~/.adk/.encryption-key` — a random 32-byte hex string auto-generated on first use.
+
 ```
-⚠ Warning: publishing 4.0.0 which is older than latest (5.0.0)
-  This will move the "latest" tag from 5.0.0 to 4.0.0.
-  Use --tag <name> to publish without affecting latest.
-Refusing to clobber latest tag. Use --tag <name> to publish 4.0.0 alongside 5.0.0.
+~/.adk/
+├── consumer-config.json    # Refs, registries, encrypted secrets
+├── .encryption-key         # AES-256-GCM key (auto-generated)
+└── refs/
+    └── notion/
+        ├── tools/              # Materialized tool schemas
+        ├── skills/             # Downloaded skill files
+        └── types/              # Generated TypeScript types
+```
+
+**Security note:** The `.encryption-key` file is currently readable by any process running as the same user, which means a coding agent can technically read it. We plan to lock this down with `0600` permissions and potentially OS keychain integration in a future release. For now, secrets are protected against casual inspection of the config file, but not against a determined local process.
+
+Override the encryption key via environment variable:
+
+```bash
+export ADK_ENCRYPTION_KEY="your-custom-key"
 ```
 
 ---
 
-## @agentdef Packages
+## Creating a Registry Server
 
-Agent definitions published to npm under the `@agentdef` scope. Like `@types` for TypeScript, but for agent tool definitions.
+A registry is a collection of agents (MCP servers) hosted behind a single endpoint. Use `createAgentServer` to host your own:
 
-### Consuming
+```typescript
+import { defineAgent, defineTool, createAgentRegistry, createAgentServer } from '@slashfi/agents-sdk';
 
-```bash
-npm install @agentdef/notion
+// Define agents
+const searchTool = defineTool({
+  name: 'search',
+  description: 'Search the database',
+  inputSchema: { type: 'object', properties: { query: { type: 'string' } }, required: ['query'] },
+  execute: async ({ query }) => ({ results: [] }),
+});
+
+const searchAgent = defineAgent({
+  path: 'search',
+  entrypoint: 'A search agent',
+  config: { name: 'Search', description: 'Search the database' },
+  tools: [searchTool],
+});
+
+// Create registry and register agents
+const registry = createAgentRegistry();
+registry.register(searchAgent);
+
+// Start the server
+const server = createAgentServer(registry, { port: 3000 });
+await server.start();
+// Clients can now: adk registry add http://localhost:3000 --name my-registry
 ```
 
-```typescript
-import definition from '@agentdef/notion';
-// definition: SerializedAgentDefinition
+The server exposes:
+- **MCP JSON-RPC** (`POST /`) — standard MCP protocol (tools/list, tools/call)
+- **Agent discovery** (`GET /agents`) — list all public agents
+- **Agent actions** (`POST /call`) — call_agent, list_agents
+- **Health check** (`GET /health`)
 
-console.log(definition.tools.length); // 22
-console.log(definition.tools[0].name); // 'API-post-search'
+Clients connect with:
+
+```bash
+adk registry add http://localhost:3000 --name my-registry
+adk registry browse my-registry
+adk ref add search --registry my-registry
 ```
 
-Access metadata:
+---
+
+## Proxy (Experimental)
 
-```typescript
-import meta from '@agentdef/notion/meta.json';
-// { hash, toolCount, sizeBytes, generatedAt, sdkVersion, changes? }
+Proxies let you forward `adk` operations to a remote server. This is useful when you want a central server to manage refs and registries on behalf of multiple users (e.g., a team server that holds shared credentials).
+
+```bash
+# Point adk at a remote server
+adk proxy add https://my-team-server.com --name team --type mcp --default
+
+# Now ref/registry operations are forwarded to the proxy
+adk ref list        # forwarded to team server
+adk ref add notion   # forwarded to team server
 ```
 
-### agent.json Format
+**Status:** Experimental. The basic add/remove/list flow works, but auth forwarding and multi-proxy routing are still being stabilized.
 
-`agent.json` is the single source of truth. Supports JSONC (comments + trailing commas).
+---
 
-```jsonc
-{
-  // Agent identity
-  "path": "notion",
-  "name": "Notion MCP Server",
-  "description": "Agent for Notion API",
-  "version": "1.0.0",
-  "visibility": "public",
-
-  // MCP server source (for re-introspection)
-  "serverSource": "npx @notionhq/notion-mcp-server",
-  "serverInfo": { "name": "Notion MCP Server", "version": "1.6.2" },
-
-  // Shared JSON Schema $defs (deduplicated across tools)
-  "$defs": { ... },
-
-  // Tool definitions
-  "tools": [
-    {
-      "name": "API-post-search",
-      "description": "Search Notion pages and databases",
-      "inputSchema": {
-        "type": "object",
-        "properties": {
-          "query": { "type": "string" }
-        }
-      }
-    }
-    // ...
-  ],
+## Using ADK as an SDK
 
-  // Generation metadata
-  "generatedAt": "2026-03-29T08:40:04.913Z",
-  "sdkVersion": "0.21.0"
-}
+The `adk` CLI is built on a pluggable SDK. The core `createAdk(fs)` factory takes an `FsStore` interface — just `readFile` and `writeFile` — so you can back it with anything:
+
+```typescript
+import { createAdk } from '@slashfi/agents-sdk';
+import type { FsStore } from '@slashfi/agents-sdk';
+
+// Local filesystem (what the CLI uses)
+import { createLocalFsStore } from '@slashfi/agents-sdk';
+const adk = createAdk(createLocalFsStore());
+
+// In-memory (for testing)
+const memFs: FsStore = {
+  _files: new Map<string, string>(),
+  async readFile(path) { return this._files.get(path) ?? null; },
+  async writeFile(path, content) { this._files.set(path, content); },
+};
+const testAdk = createAdk(memFs);
+
+// S3-backed (for serverless)
+const s3Fs: FsStore = {
+  async readFile(path) { return getFromS3(`adk/${path}`); },
+  async writeFile(path, content) { await putToS3(`adk/${path}`, content); },
+};
+const serverlessAdk = createAdk(s3Fs, { encryptionKey: process.env.ADK_KEY });
 ```
 
-### meta.json Format
+The `Adk` object exposes the same API the CLI uses:
 
-```json
-{
-  "hash": "ba845dfb",
-  "serverVersion": "1.6.2",
-  "npmPackage": "npx @notionhq/notion-mcp-server",
-  "toolCount": 22,
-  "sizeBytes": 29373,
-  "generatedAt": "2026-03-29T08:40:04.913Z",
-  "sdkVersion": "0.21.0",
-  "changes": {
-    "previousHash": "a3f8c2de",
-    "toolsAdded": ["new-tool"],
-    "toolsRemoved": [],
-    "toolsModified": ["search"],
-    "schemaChanges": ["search: added property 'filter'"]
-  }
-}
+```typescript
+// Manage registries
+await adk.registry.add({ url: 'https://registry.slash.com', name: 'public' });
+const agents = await adk.registry.browse('public');
+
+// Manage refs
+await adk.ref.add({ ref: 'notion', scheme: 'registry', sourceRegistry: { url: '...', agentPath: 'notion' } });
+const result = await adk.ref.call('notion', 'notion-search', { query: 'hello' });
+
+// Read/write config directly
+const config = await adk.readConfig();
 ```
 
+This makes it straightforward to embed `adk` in a server, a CI pipeline, or any environment where the local filesystem isn't available.
+
 ---
 
 ## Runtime API
@@ -278,7 +369,7 @@ const agent = defineAgent({
 
 ### `createClient(definition)`
 
-Create a typed client from a `SerializedAgentDefinition`. Used for consuming `@agentdef` packages at runtime.
+Create a typed client from a `SerializedAgentDefinition`.
 
 ```typescript
 import { createClient } from '@slashfi/agents-sdk';
@@ -354,18 +445,6 @@ interface SerializedAgentDefinition {
 
 All JSON files read by `adk` support JSONC (JSON with Comments):
 
-```jsonc
-{
-  // This is a comment
-  "name": "notion",
-  "tools": [
-    /* multi-line
-       comment */
-    { "name": "search" }
-  ],  // trailing commas are fine
-}
-```
-
 ```typescript
 import { parseJsonc, readJsoncFile } from '@slashfi/agents-sdk';
 
@@ -377,52 +456,27 @@ const file = readJsoncFile('./config.jsonc');
 
 ## Testing
 
-### Unit tests (tarball round-trip)
-
 ```bash
-bun test/e2e-adk.ts
-```
-
-Tests: pack → npm pack → install tarball → import → verify → version diff.
-
-### Integration tests (verdaccio)
+# Unit tests
+bun test
 
-Full registry lifecycle with a local npm registry:
+# E2E tarball round-trip
+bun test/e2e-adk.ts
 
-```bash
-# Start verdaccio
+# Integration tests with local registry
 npx verdaccio --config test/verdaccio-config.yaml --listen 4873
-
-# Run tests (in another terminal)
 bun test/e2e-verdaccio.ts
 ```
 
-Tests: publish v1 → install → publish v2 → npm update → pinned install → version listing.
-
 ---
 
-## Project Structure
+## Environment Variables
 
-```
-src/
-├── adk.ts                # ADK CLI entrypoint
-├── pack.ts               # Pack + publish logic, version diff engine
-├── introspect.ts         # MCP server introspection
-├── jsonc.ts              # JSONC parser
-├── codegen.ts            # Full codegen (TypeScript types, CLI, manifest)
-├── serialized.ts         # SerializedAgentDefinition type
-├── client.ts             # createClient()
-├── define.ts             # defineAgent(), defineTool()
-├── registry.ts           # Agent registry
-├── server.ts             # HTTP server
-├── index.ts              # Public API exports
-└── ...
-
-test/
-├── e2e-adk.ts            # Tarball round-trip test
-├── e2e-verdaccio.ts      # Full registry lifecycle test
-└── verdaccio-config.yaml # Local registry config
-```
+| Variable | Description | Default |
+|----------|-------------|--------|
+| `ADK_CONFIG_DIR` | Config directory | `~/.adk` |
+| `ADK_TOKEN` | Bearer token for authenticated registries | — |
+| `ADK_ENCRYPTION_KEY` | Override encryption key | auto from `~/.adk/.encryption-key` |
 
 ---
 

package/dist/adk.js

@@ -37,6 +37,41 @@ function getArg(flag) {
 function hasFlag(flag) {
     return args.includes(flag);
 }
+function wantsHelp() {
+    return args.includes("--help") || args.includes("-h");
+}
+const HELP_SECTIONS = {
+    proxy: `Proxy operations:
+  adk proxy add <url> --name <name> [--type mcp|registry] [--agent @config] [--default]
+  adk proxy remove <name>
+  adk proxy list`,
+    registry: `Registry operations:
+  adk registry add <url> --name <name> [--auth-type bearer|api-key|none]
+  adk registry remove <name>
+  adk registry list
+  adk registry browse <name> [--query <q>]
+  adk registry inspect <name>
+  adk registry test [name]`,
+    ref: `Ref operations:
+  adk ref add <name>                     Install from default (public) registry
+  adk ref add <name> --registry <reg>    Install from a specific registry
+  adk ref add <name> --url <url>         Install from a direct URL
+  adk ref remove <name>
+  adk ref list
+  adk ref get <name>
+  adk ref inspect <name> [--full]
+  adk ref call <name> <tool> [params_json]
+  adk ref resources <name>
+  adk ref read <name> <uri> [uri...]
+  adk ref auth <name> [--api-key <key>]
+  adk ref auth-status <name>
+
+Examples:
+  adk ref add notion                     # Install from public registry
+  adk ref add notion --registry internal # Install from "internal" registry
+  adk ref add myapi --url https://api.example.com/mcp
+  adk ref call notion notion-search '{"query":"hello"}'`,
+};
 function getAdk() {
     const token = process.env.ADK_TOKEN ?? undefined;
     const encryptionKey = getLocalEncryptionKey();
@@ -107,6 +142,10 @@ Examples:
 // Commands
 // ============================================
 async function runProxy() {
+    if (wantsHelp()) {
+        console.log(HELP_SECTIONS.proxy);
+        process.exit(0);
+    }
     const op = args[1];
     const adk = getAdk();
     switch (op) {
@@ -159,6 +198,10 @@ async function runProxy() {
 // Registry CLI
 // ============================================
 async function runRegistry() {
+    if (wantsHelp()) {
+        console.log(HELP_SECTIONS.registry);
+        process.exit(0);
+    }
     const op = args[1];
     const adk = getAdk();
     switch (op) {
@@ -259,6 +302,10 @@ async function runRegistry() {
 // Ref CLI
 // ============================================
 async function runRef() {
+    if (wantsHelp()) {
+        console.log(HELP_SECTIONS.ref);
+        process.exit(0);
+    }
     const op = args[1];
     const adk = getAdk();
     switch (op) {