@sisu-ai/server 1.0.0

package/README.md

@@ -0,0 +1,89 @@
+# @sisu-ai/server
+
+Standalone HTTP/HTTPS adapter for Sisu agents. Spin up an HTTP server or attach to an existing one while keeping the small core philosophy.
+
+## Setup
+
+```bash
+npm i @sisu-ai/server
+```
+
+## Usage
+
+```ts
+import { Agent } from '@sisu-ai/core';
+import { Server } from '@sisu-ai/server';
+import { agentRunApi } from '@sisu-ai/mw-agent-run-api';
+
+const app = new Agent().use(agentRunApi());
+const server = new Server(app, {
+  port: 3000,
+  // Optional banner (enabled by default). Add endpoints to list them.
+  bannerEndpoints: [
+    'POST /api/runs/start',
+    'GET  /api/runs/:id/status',
+    'GET  /api/runs/:id/stream',
+    'POST /api/runs/:id/cancel',
+  ],
+  createCtx: (req, res) => ({ req, res, messages: [], signal: new AbortController().signal })
+});
+server.listen();
+```
+
+## Options
+
+- port/host/backlog/path/tls: standard Node listen options.
+- basePath: base URL path for your agent routes. Default: `/api`.
+- healthPath: health endpoint or `false` to disable. Default: `/health`.
+- createCtx(req, res): build your per-request context; `Server` injects `agent` and a default `log` if missing.
+- logBanner: print a startup banner. Default: `true`.
+- bannerEndpoints: string lines printed under the banner (e.g., `GET /api/runs/:id/status`).
+- logLevel: `'debug' | 'info' | 'warn' | 'error'`; sets the default console logger level.
+- logger: provide a custom logger implementing Sisu `Logger`.
+- redactLogKeys: additional keys to redact in logs (merged with built-ins).
+
+## Request Logging
+
+The server emits basic structured logs for every request and response using the default logger (or your `logger`).
+
+- Request: `[server] request { method, url }`
+- Response: `[server] response { method, url, status, duration_ms }`
+
+Control verbosity via `logLevel` or `LOG_LEVEL`.
+
+## Events API
+
+Subscribe to server lifecycle and per-request events without using the `listen` callback.
+
+```ts
+const server = new Server(app, { port: 3000 });
+
+server
+  .on('listening', ({ url }) => {
+    console.log('ready at', url);
+  })
+  .on('request', ({ method, url }) => {
+    // e.g., metrics, audit
+  })
+  .on('response', ({ method, url, status, duration_ms }) => {
+    // e.g., record duration_ms to your metrics system
+  })
+  .on('error', (err) => {
+    console.error('server error', err);
+  })
+  .on('close', () => {
+    console.log('server closed');
+  });
+
+server.listen();
+```
+
+### Features
+
+- Health endpoint (`/health` by default)
+- Attach to existing `http`/`https` server or listen directly
+- Supports TLS and UNIX sockets
+- Injects the agent into each request context so middleware can spawn runs
+ - Startup banner: prints listen address, health path, base path, and optional endpoints
+ - Request logs: per-request/response lines, redaction support
+ - Events API: `listening`, `request`, `response`, `error`, `close`

package/dist/index.d.ts

@@ -0,0 +1,84 @@
+import http, { type IncomingMessage, type ServerResponse } from 'http';
+import https from 'https';
+import type { Agent, Logger } from '@sisu-ai/core';
+import type { AddressInfo } from 'net';
+export { matchRoute } from './router.js';
+export interface ListenOptions<Ctx> {
+    tls?: https.ServerOptions;
+    port?: number;
+    host?: string;
+    backlog?: number;
+    path?: string;
+    basePath?: string;
+    createCtx?: (req: IncomingMessage, res: ServerResponse) => Promise<Ctx> | Ctx;
+    healthPath?: string | false;
+    logBanner?: boolean;
+    bannerEndpoints?: string[];
+    logger?: Logger;
+    logLevel?: 'debug' | 'info' | 'warn' | 'error';
+    redactLogKeys?: string[];
+}
+export declare class Server<Ctx = any> {
+    private agent;
+    private opts;
+    private server?;
+    private basePath;
+    private healthPath;
+    private createCtx;
+    private emitter;
+    constructor(agent: Agent<any>, opts?: ListenOptions<Ctx>);
+    private handle;
+    listener(): (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+    listen(cb?: () => void): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse> | https.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
+    attach(server: http.Server | https.Server): void;
+    close(cb?: (err?: Error) => void): void;
+    address(): string | AddressInfo | null | undefined;
+    on(event: 'listening', handler: (e: {
+        url: string;
+        address: string | AddressInfo | null | undefined;
+    }) => void): this;
+    on(event: 'request', handler: (e: {
+        method: string;
+        url: string;
+    }) => void): this;
+    on(event: 'response', handler: (e: {
+        method: string;
+        url: string;
+        status: number;
+        duration_ms: number;
+    }) => void): this;
+    on(event: 'error', handler: (err: Error) => void): this;
+    on(event: 'close', handler: () => void): this;
+    once(event: 'listening', handler: (e: {
+        url: string;
+        address: string | AddressInfo | null | undefined;
+    }) => void): this;
+    once(event: 'request', handler: (e: {
+        method: string;
+        url: string;
+    }) => void): this;
+    once(event: 'response', handler: (e: {
+        method: string;
+        url: string;
+        status: number;
+        duration_ms: number;
+    }) => void): this;
+    once(event: 'error', handler: (err: Error) => void): this;
+    once(event: 'close', handler: () => void): this;
+    off(event: 'listening', handler: (e: {
+        url: string;
+        address: string | AddressInfo | null | undefined;
+    }) => void): this;
+    off(event: 'request', handler: (e: {
+        method: string;
+        url: string;
+    }) => void): this;
+    off(event: 'response', handler: (e: {
+        method: string;
+        url: string;
+        status: number;
+        duration_ms: number;
+    }) => void): this;
+    off(event: 'error', handler: (err: Error) => void): this;
+    off(event: 'close', handler: () => void): this;
+}

package/dist/index.js

@@ -0,0 +1,121 @@
+import http from 'http';
+import https from 'https';
+import { createConsoleLogger, createRedactingLogger } from '@sisu-ai/core';
+import { EventEmitter } from 'events';
+export { matchRoute } from './router.js';
+export class Server {
+    constructor(agent, opts = {}) {
+        this.agent = agent;
+        this.opts = opts;
+        this.emitter = new EventEmitter();
+        this.basePath = opts.basePath ?? '/api';
+        this.healthPath = opts.healthPath ?? '/health';
+        this.createCtx = opts.createCtx ?? ((req, res) => ({ req, res }));
+    }
+    async handle(req, res) {
+        // Set up server-level request logging (independent of ctx)
+        const baseLogger = this.opts.logger ?? createConsoleLogger({ level: this.opts.logLevel, timestamps: true });
+        const srvLogger = createRedactingLogger(baseLogger, { keys: this.opts.redactLogKeys });
+        const started = Date.now();
+        const { method = 'GET', url = '' } = req;
+        srvLogger.info?.('[server] request', { method, url });
+        res.once?.('finish', () => {
+            const ms = Date.now() - started;
+            srvLogger.info?.('[server] response', { method, url, status: res.statusCode, duration_ms: ms });
+            this.emitter.emit('response', { method, url, status: res.statusCode, duration_ms: ms });
+        });
+        this.emitter.emit('request', { method, url });
+        if (this.healthPath && req.url === this.healthPath) {
+            res.statusCode = 200;
+            res.end('ok');
+            return;
+        }
+        if (!req.url || !req.url.startsWith(this.basePath)) {
+            res.statusCode = 404;
+            res.end();
+            return;
+        }
+        const ctx = await this.createCtx(req, res);
+        ctx.agent = this.agent;
+        // Provide a default logger if not present, mirroring CLI behavior
+        if (!ctx.log) {
+            ctx.log = srvLogger;
+        }
+        // Mark this context as an HTTP transport envelope and capture minimal request meta
+        const headers = req.headers || {};
+        const httpMeta = {
+            method: req.method || 'GET',
+            url: req.url || '',
+            ip: (req.socket && (req.socket.remoteAddress || '')) || '',
+            headers: {
+                'user-agent': typeof headers['user-agent'] === 'string' ? headers['user-agent'] : undefined,
+                'accept': typeof headers['accept'] === 'string' ? headers['accept'] : undefined,
+                'content-type': typeof headers['content-type'] === 'string' ? headers['content-type'] : undefined,
+            },
+        };
+        ctx.state = { ...(ctx.state ?? {}), _transport: { type: 'http' }, _http: httpMeta };
+        const handler = this.agent.handler();
+        await handler(ctx);
+        // Only synthesize a 404 when nothing has been written at all.
+        // If headers were sent (e.g., SSE), keep the connection as-is.
+        if (!res.writableEnded && !res.headersSent) {
+            res.statusCode = 404;
+            res.end();
+        }
+    }
+    listener() {
+        return this.handle.bind(this);
+    }
+    listen(cb) {
+        const listener = this.listener();
+        this.server = this.opts.tls
+            ? https.createServer(this.opts.tls, listener)
+            : http.createServer(listener);
+        if (this.opts.path) {
+            this.server.listen(this.opts.path, cb);
+        }
+        else {
+            this.server.listen(this.opts.port ?? 0, this.opts.host, this.opts.backlog, cb);
+        }
+        this.server.on('error', (err) => this.emitter.emit('error', err));
+        this.server.on('close', () => this.emitter.emit('close'));
+        const printBanner = this.opts.logBanner !== false;
+        if (printBanner) {
+            const addr = this.server.address();
+            let url = '';
+            if (typeof addr === 'object' && addr && 'port' in addr) {
+                const host = this.opts.host && this.opts.host !== '0.0.0.0' ? this.opts.host : 'localhost';
+                url = `http://${host}:${addr.port}`;
+            }
+            else if (typeof addr === 'string') {
+                url = addr;
+            }
+            if (url)
+                console.log(`[server] listening on ${url}`);
+            if (this.healthPath)
+                console.log(`[server] health: GET ${this.healthPath}`);
+            if (this.basePath)
+                console.log(`[server] basePath: ${this.basePath}`);
+            if (this.opts.bannerEndpoints?.length) {
+                console.log('[server] endpoints:');
+                for (const ep of this.opts.bannerEndpoints)
+                    console.log(`  ${ep}`);
+            }
+            this.emitter.emit('listening', { url, address: addr });
+        }
+        return this.server;
+    }
+    attach(server) {
+        server.on('request', this.listener());
+        this.server = server;
+    }
+    close(cb) {
+        this.server?.close(cb);
+    }
+    address() {
+        return this.server?.address();
+    }
+    on(event, handler) { this.emitter.on(event, handler); return this; }
+    once(event, handler) { this.emitter.once(event, handler); return this; }
+    off(event, handler) { this.emitter.off(event, handler); return this; }
+}

package/dist/router.d.ts

@@ -0,0 +1,3 @@
+export declare function matchRoute(url: string, basePath: string, template: string): {
+    params: Record<string, string>;
+} | null;

package/dist/router.js

@@ -0,0 +1,28 @@
+// Lightweight path matcher for server + middleware
+// Example: matchRoute('/api/runs/123/status', '/api', '/runs/:id/status')
+//   => { params: { id: '123' } }
+export function matchRoute(url, basePath, template) {
+    if (!url.startsWith(basePath))
+        return null;
+    const q = url.indexOf('?');
+    const path = url.slice(basePath.length, q >= 0 ? q : undefined) || '/';
+    const tSegs = template.split('/').filter(Boolean);
+    const pSegs = path.split('/').filter(Boolean);
+    if (tSegs.length !== pSegs.length)
+        return null;
+    const params = {};
+    for (let i = 0; i < tSegs.length; i++) {
+        const t = tSegs[i];
+        const p = pSegs[i];
+        if (t.startsWith(':')) {
+            const name = t.slice(1);
+            if (!name)
+                return null;
+            params[name] = p;
+        }
+        else if (t !== p) {
+            return null;
+        }
+    }
+    return { params };
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@sisu-ai/server",
+  "version": "1.0.0",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -b"
+  },
+  "peerDependencies": {
+    "@sisu-ai/core": "1.0.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/finger-gun/sisu",
+    "directory": "packages/server"
+  },
+  "homepage": "https://github.com/finger-gun/sisu#readme",
+  "bugs": {
+    "url": "https://github.com/finger-gun/sisu/issues"
+  },
+  "keywords": [
+    "sisu",
+    "ai",
+    "server",
+    "adapter"
+  ]
+}