@slashfi/agents-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Slash Financial
+
+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,274 @@
+# Agents SDK
+
+SDK for building AI agents with tool definitions and JSON-RPC servers.
+
+## Installation
+
+```bash
+bun add @slashfi/agents-sdk
+# or
+npm install @slashfi/agents-sdk
+```
+
+## Quick Start
+
+```typescript
+import {
+  defineAgent,
+  defineTool,
+  createAgentRegistry,
+  createAgentServer
+} from '@slashfi/agents-sdk';
+
+// Define a tool
+const greet = defineTool({
+  name: 'greet',
+  description: 'Greet a user',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      name: { type: 'string', description: 'Name to greet' }
+    },
+    required: ['name']
+  },
+  execute: async (input: { name: string }) => {
+    return { message: `Hello, ${input.name}!` };
+  }
+});
+
+// Define an agent
+const agent = defineAgent({
+  path: '@my-agent',
+  entrypoint: 'You are a helpful assistant.',
+  config: {
+    name: 'My Agent',
+    description: 'A helpful agent that can greet users'
+  },
+  tools: [greet]
+});
+
+// Create registry and register agent
+const registry = createAgentRegistry();
+registry.register(agent);
+
+// Start HTTP server
+const server = createAgentServer(registry, { port: 3000 });
+await server.start();
+```
+
+## API
+
+### `defineTool(options)`
+
+Create a tool definition.
+
+```typescript
+const tool = defineTool({
+  name: 'tool-name',
+  description: 'What the tool does',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      param: { type: 'string', description: 'Parameter description' }
+    },
+    required: ['param']
+  },
+  execute: async (input, ctx) => {
+    // Tool implementation
+    return result;
+  }
+});
+```
+
+### `defineAgent(options)`
+
+Create an agent definition.
+
+```typescript
+const agent = defineAgent({
+  path: '@agent-name',
+  entrypoint: 'System prompt for the agent',
+  config: {
+    name: 'Agent Name',
+    description: 'Agent description',
+    supportedActions: ['execute_tool', 'describe_tools', 'load']
+  },
+  tools: [tool1, tool2]
+});
+```
+
+### `createAgentRegistry(options?)`
+
+Create an agent registry to manage agents.
+
+```typescript
+const registry = createAgentRegistry({
+  defaultVisibility: 'internal' // 'public' | 'internal' | 'private'
+});
+
+registry.register(agent);
+registry.list(); // Returns all registered agents
+registry.get('@agent-name'); // Get agent by path
+
+// Call an agent
+const result = await registry.call({
+  action: 'execute_tool',
+  path: '@agent-name',
+  tool: 'tool-name',
+  params: { param: 'value' }
+});
+```
+
+### `createAgentServer(registry, options?)`
+
+Create an HTTP server exposing the registry.
+
+```typescript
+const server = createAgentServer(registry, {
+  port: 3000,
+  hostname: 'localhost',
+  basePath: '/api',
+  cors: true
+});
+
+await server.start();
+// POST /api/call - Execute agent actions
+// GET  /api/list - List agents
+
+await server.stop();
+```
+
+## HTTP Endpoints
+
+### POST /call
+
+Execute an agent action.
+
+**Request:**
+```json
+{
+  "action": "execute_tool",
+  "path": "@my-agent",
+  "tool": "greet",
+  "params": { "name": "World" }
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "result": { "message": "Hello, World!" }
+}
+```
+
+**Actions:**
+- `execute_tool` - Execute a specific tool
+- `describe_tools` - Get tool schemas
+- `load` - Get agent definition
+
+### GET /list
+
+List registered agents.
+
+**Response:**
+```json
+{
+  "success": true,
+  "agents": [
+    {
+      "path": "@my-agent",
+      "name": "My Agent",
+      "description": "A helpful agent",
+      "supportedActions": ["execute_tool", "describe_tools", "load"]
+    }
+  ]
+}
+```
+
+## Access Control
+
+Agents and tools support visibility levels:
+
+- `public` - Anyone can access
+- `internal` - Only other agents in the same registry
+- `private` - Only the owning agent
+
+```typescript
+const agent = defineAgent({
+  path: '@private-agent',
+  entrypoint: '...',
+  visibility: 'internal',
+  allowedCallers: ['@trusted-agent'] // Explicit allowlist
+});
+```
+
+## Filesystem Convention
+
+Organize agents using the filesystem convention:
+
+```
+src/agents/
+├── @my-agent/
+│   ├── entrypoint.md      # System prompt
+│   ├── agent.config.ts    # Configuration
+│   ├── greet.tool.ts      # Tool (exports greetTool)
+│   └── echo.tool.ts       # Tool (exports echoTool)
+└── @another-agent/
+    └── ...
+```
+
+### Build Script
+
+Use `buildAgents` to generate the registry at build time:
+
+```typescript
+// scripts/build-agents.ts
+import { buildAgents } from '@slashfi/agents-sdk';
+
+const result = await buildAgents({
+  agentsDir: './src/agents',
+  outFile: './src/agents/_generated-registry.ts',
+});
+
+console.log(`Built ${result.agentCount} agents: ${result.agents.join(', ')}`);
+```
+
+Run before TypeScript compilation:
+
+```bash
+bun scripts/build-agents.ts && bun run build
+```
+
+### File Conventions
+
+**entrypoint.md** - System prompt for the agent (markdown)
+
+**agent.config.ts** - Agent configuration:
+```typescript
+import type { AgentConfig } from '@slashfi/agents-sdk';
+
+const config: AgentConfig = {
+  name: 'My Agent',
+  description: 'Does things',
+  supportedActions: ['execute_tool', 'describe_tools', 'load'],
+};
+
+export default config;
+```
+
+**{name}.tool.ts** - Tool definition (exports `{name}Tool`):
+```typescript
+import { defineTool } from '@slashfi/agents-sdk';
+
+export const greetTool = defineTool({
+  name: 'greet',
+  description: 'Greet a user',
+  inputSchema: { ... },
+  execute: async (input) => ({ message: `Hello!` }),
+});
+```
+
+## License
+
+MIT

package/dist/auth.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Auth Agent
+ *
+ * Built-in agent that provides OAuth2 client_credentials authentication.
+ * Register it into any agent registry to enable auth.
+ *
+ * Features:
+ * - Client credentials management (create, rotate, revoke)
+ * - OAuth2 client_credentials token exchange
+ * - JWT access tokens with scopes
+ * - Pluggable AuthStore interface (in-memory default)
+ * - Root key for admin operations
+ *
+ * @example
+ * ```typescript
+ * import { createAgentRegistry, createAgentServer, createAuthAgent } from '@slashfi/agents-sdk';
+ *
+ * const registry = createAgentRegistry();
+ * registry.register(createAuthAgent({ rootKey: process.env.ROOT_KEY }));
+ * registry.register(myAgent);
+ *
+ * const server = createAgentServer(registry, { port: 3000 });
+ * await server.start();
+ * ```
+ */
+import type { AgentDefinition } from "./types.js";
+/** Registered client */
+export interface AuthClient {
+    clientId: string;
+    clientSecretHash: string;
+    name: string;
+    scopes: string[];
+    createdAt: number;
+    /** If true, this client was created via self-registration */
+    selfRegistered?: boolean;
+}
+/** Issued token metadata */
+export interface AuthToken {
+    token: string;
+    clientId: string;
+    scopes: string[];
+    expiresAt: number;
+    issuedAt: number;
+}
+/** Resolved identity from a token or root key */
+export interface AuthIdentity {
+    clientId: string;
+    name: string;
+    scopes: string[];
+    isRoot: boolean;
+}
+/**
+ * Pluggable storage for auth state.
+ * Implement this interface to use Postgres, Redis, SQLite, etc.
+ */
+export interface AuthStore {
+    /** Create a new client. Returns the raw (unhashed) secret. */
+    createClient(name: string, scopes: string[], selfRegistered?: boolean): Promise<{
+        clientId: string;
+        clientSecret: string;
+    }>;
+    /** Validate client credentials. Returns client if valid, null otherwise. */
+    validateClient(clientId: string, clientSecret: string): Promise<AuthClient | null>;
+    /** Get client by ID. */
+    getClient(clientId: string): Promise<AuthClient | null>;
+    /** List all clients. */
+    listClients(): Promise<AuthClient[]>;
+    /** Revoke a client (delete). */
+    revokeClient(clientId: string): Promise<boolean>;
+    /** Rotate a client's secret. Returns new raw secret. */
+    rotateSecret(clientId: string): Promise<{
+        clientSecret: string;
+    } | null>;
+    /** Store a token. */
+    storeToken(token: AuthToken): Promise<void>;
+    /** Validate and retrieve a token. Returns null if invalid/expired. */
+    validateToken(tokenString: string): Promise<AuthToken | null>;
+    /** Revoke a specific token. */
+    revokeToken(tokenString: string): Promise<boolean>;
+}
+/**
+ * Create an in-memory auth store.
+ * Suitable for development and testing. Use a persistent store for production.
+ */
+export declare function createMemoryAuthStore(): AuthStore;
+export interface CreateAuthAgentOptions {
+    /** Root key for admin operations. Required. */
+    rootKey: string;
+    /** Allow self-registration via public `register` tool. Default: false */
+    allowRegistration?: boolean;
+    /** Max scopes that self-registered clients can request. Default: [] (no limit) */
+    registrationScopes?: string[];
+    /** Token TTL in seconds. Default: 3600 (1 hour) */
+    tokenTtl?: number;
+    /** Custom auth store. Default: in-memory */
+    store?: AuthStore;
+}
+/**
+ * Create the built-in `@auth` agent.
+ *
+ * Provides OAuth2 client_credentials authentication as agent tools.
+ * The server auto-detects this agent and wires up token validation.
+ */
+export declare function createAuthAgent(options: CreateAuthAgentOptions): AgentDefinition & {
+    __authStore: AuthStore;
+    __rootKey: string;
+    __tokenTtl: number;
+};
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAGH,OAAO,KAAK,EAAE,eAAe,EAA+B,MAAM,YAAY,CAAC;AAM/E,wBAAwB;AACxB,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,MAAM,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,6DAA6D;IAC7D,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,4BAA4B;AAC5B,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,iDAAiD;AACjD,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;CACjB;AAMD;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,8DAA8D;IAC9D,YAAY,CACV,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EAAE,EAChB,cAAc,CAAC,EAAE,OAAO,GACvB,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAEvD,4EAA4E;IAC5E,cAAc,CACZ,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IAE9B,wBAAwB;IACxB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IAExD,wBAAwB;IACxB,WAAW,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;IAErC,gCAAgC;IAChC,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEjD,wDAAwD;IACxD,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,YAAY,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;IAEzE,qBAAqB;IACrB,UAAU,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5C,sEAAsE;IACtE,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;IAE9D,+BAA+B;IAC/B,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACpD;AA6CD;;;GAGG;AACH,wBAAgB,qBAAqB,IAAI,SAAS,CAyEjD;AAMD,MAAM,WAAW,sBAAsB;IACrC,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAC;IAEhB,yEAAyE;IACzE,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAE5B,kFAAkF;IAClF,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAE9B,mDAAmD;IACnD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,4CAA4C;IAC5C,KAAK,CAAC,EAAE,SAAS,CAAC;CACnB;AAMD;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,sBAAsB,GAC9B,eAAe,GAAG;IACnB,WAAW,EAAE,SAAS,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB,CAoOA"}