@agentuity/server 0.0.3 → 0.0.4

package/AGENTS.md

@@ -0,0 +1,124 @@
+# Agent Guidelines for @agentuity/server
+
+## Package Overview
+
+Server runtime for building Agentuity applications. Built on Hono framework and optimized for Bun runtime with OpenTelemetry observability.
+
+## Commands
+
+- **Build**: `bun run build` (compiles for Bun target)
+- **Typecheck**: `bun run typecheck` (runs TypeScript type checking)
+- **Clean**: `bun run clean` (removes dist/)
+
+## Architecture
+
+- **Runtime**: Bun server runtime
+- **Framework**: Hono (lightweight web framework)
+- **Build target**: Bun runtime
+- **Dependencies**: `@agentuity/core`, Hono, OpenTelemetry
+- **Observability**: Built-in OpenTelemetry for logs, traces, and metrics
+
+## Structure
+
+```
+src/
+├── index.ts        # Main exports
+├── app.ts          # createApp() function
+├── agent.ts        # Agent types and defineAgent()
+├── router.ts       # createRouter() with extended methods
+├── logger.ts       # Logging utilities
+├── _server.ts      # Internal server creation
+├── _context.ts     # Internal context management
+└── _util.ts        # Internal utilities
+```
+
+## Code Style
+
+- **Hono patterns** - Follow Hono's context-based API design
+- **Type safety** - Extensive use of TypeScript generics
+- **Middleware pattern** - Support Hono middleware
+- **Async handlers** - All handlers can be async
+- **OpenTelemetry** - Use tracer/logger from context
+
+## Important Conventions
+
+- **Agent context** - Every agent handler receives `AgentContext` as first parameter
+- **Schema validation** - Support StandardSchemaV1 (works with Zod, Valibot, etc.)
+- **Streaming support** - Agents can return ReadableStream for streaming responses
+- **WebSocket support** - Use `router.websocket()` for WebSocket routes
+- **SSE support** - Use `router.sse()` for Server-Sent Events
+- **Session tracking** - Each request gets unique sessionId
+- **Storage abstractions** - Provide kv, objectstore, stream, vector interfaces
+
+## Agent Definition Pattern
+
+```typescript
+import { defineAgent } from '@agentuity/server';
+import { z } from 'zod';
+
+export default defineAgent({
+  metadata: {
+    id: 'unique-id',
+    identifier: 'folder-name',
+    name: 'Human Name',
+    description: 'What it does',
+    filename: __filename,
+    version: 'hash-or-version'
+  },
+  inputSchema: z.object({ /* ... */ }),
+  outputSchema: z.object({ /* ... */ }),
+  handler: async (ctx, input) => {
+    // ctx.logger, ctx.tracer, ctx.kv, etc.
+    return output;
+  }
+});
+```
+
+## Router Extensions
+
+The `createRouter()` function returns an extended Hono instance with:
+
+- **Standard HTTP methods**: `get`, `post`, `put`, `delete`, `patch`
+- **Streaming**: `stream(path, handler)` - Returns ReadableStream
+- **WebSocket**: `websocket(path, handler)` - WebSocket connections
+- **SSE**: `sse(path, handler)` - Server-Sent Events
+
+## AgentContext API
+
+Every agent handler receives:
+
+```typescript
+interface AgentContext {
+  logger: Logger;              // Structured logger
+  tracer: Tracer;             // OpenTelemetry tracer
+  sessionId: string;          // Unique session ID
+  kv: KeyValueStorage;        // Key-value storage
+  objectstore: ObjectStorage; // Object storage
+  stream: StreamStorage;      // Stream storage
+  vector: VectorStorage;      // Vector storage
+  agent: AgentRegistry;       // Access other agents
+  waitUntil: (promise) => void; // Background tasks
+}
+```
+
+## Observability
+
+- **Logging**: Use `ctx.logger.info/warn/error()` not console.log
+- **Tracing**: Create spans with `ctx.tracer.startSpan()`
+- **Metrics**: Access via `c.var.meter` in Hono context
+- **Environment**: Metrics/traces sent to OTLP endpoints
+
+## Testing
+
+- Use Bun's test runner: `bun test`
+- Mock storage interfaces (kv, objectstore, etc.)
+- Test agent handlers with mock context
+- Use Hono's testing utilities for routes
+
+## Publishing Checklist
+
+1. Run `bun run build` to compile for Bun runtime
+2. Verify OpenTelemetry dependencies are correct versions
+3. Test with real Hono server
+4. Must publish **after** @agentuity/core
+5. Ensure React is only in devDependencies (for type checking web components)

package/README.md

@@ -0,0 +1,220 @@
+# @agentuity/server
+
+Server runtime for building Agentuity applications with Bun and Hono.
+
+## Installation
+
+```bash
+bun add @agentuity/server
+```
+
+## Overview
+
+`@agentuity/server` provides the server-side runtime for Agentuity applications. Built on [Hono](https://hono.dev/) and optimized for [Bun](https://bun.sh/), it enables you to create type-safe agents with automatic routing, validation, and observability.
+
+## Quick Start
+
+### Creating an Application
+
+```typescript
+import { createApp } from '@agentuity/server';
+
+const { app, server, logger } = createApp();
+
+// Start the server
+server.listen(3000);
+logger.info('Server running on http://localhost:3000');
+```
+
+### Defining an Agent
+
+```typescript
+import { defineAgent } from '@agentuity/server';
+import { z } from 'zod';
+
+const myAgent = defineAgent({
+  metadata: {
+    id: 'my-agent',
+    identifier: 'my-agent',
+    name: 'My Agent',
+    description: 'Example agent',
+    filename: 'src/agents/my-agent/agent.ts',
+    version: '1.0.0'
+  },
+  inputSchema: z.object({
+    message: z.string()
+  }),
+  outputSchema: z.object({
+    response: z.string()
+  }),
+  handler: async (ctx, input) => {
+    ctx.logger.info('Processing message:', input.message);
+    return { response: `You said: ${input.message}` };
+  }
+});
+
+export default myAgent;
+```
+
+### Creating Custom Routes
+
+```typescript
+import { createRouter } from '@agentuity/server';
+
+const router = createRouter();
+
+router.get('/hello', (c) => {
+  return c.json({ message: 'Hello, world!' });
+});
+
+router.post('/data', async (c) => {
+  const body = await c.req.json();
+  return c.json({ received: body });
+});
+
+export default router;
+```
+
+### Streaming Responses
+
+```typescript
+router.stream('/events', async (c) => {
+  return new ReadableStream({
+    start(controller) {
+      controller.enqueue('Event 1\n');
+      controller.enqueue('Event 2\n');
+      controller.close();
+    }
+  });
+});
+```
+
+### WebSocket Support
+
+```typescript
+router.websocket('/chat', (c) => (ws) => {
+  ws.onOpen(() => {
+    console.log('Client connected');
+  });
+
+  ws.onMessage((event) => {
+    const data = JSON.parse(event.data);
+    ws.send(JSON.stringify({ echo: data }));
+  });
+
+  ws.onClose(() => {
+    console.log('Client disconnected');
+  });
+});
+```
+
+### Server-Sent Events (SSE)
+
+```typescript
+router.sse('/updates', (c) => async (stream) => {
+  for (let i = 0; i < 10; i++) {
+    await stream.writeSSE({
+      data: JSON.stringify({ count: i }),
+      event: 'update'
+    });
+    await stream.sleep(1000);
+  }
+});
+```
+
+## API Reference
+
+### createApp(config?)
+
+Creates a new Agentuity application instance.
+
+**Returns:**
+- `app` - Hono application instance
+- `server` - Server instance with `listen()` method
+- `logger` - Structured logger
+
+### defineAgent(config)
+
+Defines a type-safe agent with input/output validation.
+
+**Config:**
+- `metadata` - Agent metadata (id, name, description, etc.)
+- `inputSchema?` - Schema for input validation (Zod, Valibot, etc.)
+- `outputSchema?` - Schema for output validation
+- `stream?` - Whether the agent returns a stream
+- `handler` - Agent handler function
+
+### createRouter()
+
+Creates a new router for defining custom API routes.
+
+**Methods:**
+- `get/post/put/delete/patch` - HTTP method handlers
+- `stream(path, handler)` - Streaming response handler
+- `websocket(path, handler)` - WebSocket handler
+- `sse(path, handler)` - Server-Sent Events handler
+
+### AgentContext
+
+Context object available in agent handlers:
+
+```typescript
+interface AgentContext {
+  logger: Logger;              // Structured logger
+  tracer: Tracer;             // OpenTelemetry tracer
+  sessionId: string;          // Unique session ID
+  kv: KeyValueStorage;        // Key-value storage
+  objectstore: ObjectStorage; // Object storage
+  stream: StreamStorage;      // Stream storage
+  vector: VectorStorage;      // Vector storage
+  agent: AgentRegistry;       // Access to other agents
+  waitUntil: (promise) => void; // Defer cleanup tasks
+}
+```
+
+## Storage Services
+
+Agentuity provides built-in storage abstractions:
+
+- **KeyValueStorage** - Simple key-value storage
+- **ObjectStorage** - Object/blob storage
+- **StreamStorage** - Streaming data storage
+- **VectorStorage** - Vector embeddings storage
+
+Access these via the agent context:
+
+```typescript
+const myAgent = defineAgent({
+  handler: async (ctx, input) => {
+    await ctx.kv.set('key', 'value');
+    const value = await ctx.kv.get('key');
+    return { value };
+  }
+});
+```
+
+## Observability
+
+Built-in OpenTelemetry support for logging, tracing, and metrics:
+
+```typescript
+const myAgent = defineAgent({
+  handler: async (ctx, input) => {
+    ctx.logger.info('Processing request');
+    
+    const span = ctx.tracer.startSpan('custom-operation');
+    // ... do work ...
+    span.end();
+    
+    return { success: true };
+  }
+});
+```
+
+## TypeScript
+
+Fully typed with TypeScript. Input and output types are automatically inferred from your schemas.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@agentuity/server",
-	"version": "0.0.3",
+	"version": "0.0.4",
 	"type": "module",
 	"main": "./src/index.ts",
 	"types": "./dist/index.d.ts",
@@ -11,6 +11,7 @@
 		}
 	},
 	"files": [
+		"AGENTS.md",
 		"README.md",
 		"src",
 		"dist"