@neeter/server 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dan Leeper
+
+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/dist/index.d.ts

@@ -0,0 +1,6 @@
+export type { CustomEvent, SSEEvent } from "@neeter/types";
+export { PermissionGate } from "./permission-gate.js";
+export { PushChannel } from "./push-channel.js";
+export { createAgentRouter } from "./router.js";
+export { type Session, type SessionInit, SessionManager } from "./session.js";
+export { MessageTranslator, sseEncode, streamSession, type TranslatorConfig, } from "./translator.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { PermissionGate } from "./permission-gate.js";
+export { PushChannel } from "./push-channel.js";
+export { createAgentRouter } from "./router.js";
+export { SessionManager } from "./session.js";
+export { MessageTranslator, sseEncode, streamSession, } from "./translator.js";

package/dist/permission-gate.d.ts

@@ -0,0 +1,12 @@
+import type { PermissionRequest, PermissionResponse } from "@neeter/types";
+type RequestListener = (request: PermissionRequest) => void;
+export declare class PermissionGate {
+    private pending;
+    private listeners;
+    request(permissionRequest: PermissionRequest): Promise<PermissionResponse>;
+    respond(response: PermissionResponse): boolean;
+    onRequest(listener: RequestListener): () => void;
+    getPending(): PermissionRequest[];
+    cancelAll(message: string): void;
+}
+export {};

package/dist/permission-gate.js

@@ -0,0 +1,41 @@
+export class PermissionGate {
+    pending = new Map();
+    listeners = new Set();
+    request(permissionRequest) {
+        return new Promise((resolve) => {
+            this.pending.set(permissionRequest.requestId, {
+                request: permissionRequest,
+                resolve,
+            });
+            for (const listener of this.listeners) {
+                listener(permissionRequest);
+            }
+        });
+    }
+    respond(response) {
+        const entry = this.pending.get(response.requestId);
+        if (!entry)
+            return false;
+        this.pending.delete(response.requestId);
+        entry.resolve(response);
+        return true;
+    }
+    onRequest(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    getPending() {
+        return [...this.pending.values()].map((p) => p.request);
+    }
+    cancelAll(message) {
+        for (const [id, entry] of this.pending) {
+            if (entry.request.kind === "tool_approval") {
+                entry.resolve({ kind: "tool_approval", requestId: id, behavior: "deny", message });
+            }
+            else {
+                entry.resolve({ kind: "user_question", requestId: id, answers: {} });
+            }
+        }
+        this.pending.clear();
+    }
+}

package/dist/push-channel.d.ts

@@ -0,0 +1,8 @@
+export declare class PushChannel<T> implements AsyncIterable<T> {
+    private queue;
+    private resolve;
+    private done;
+    push(value: T): void;
+    close(): void;
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+}

package/dist/push-channel.js

@@ -0,0 +1,40 @@
+export class PushChannel {
+    queue = [];
+    resolve = null;
+    done = false;
+    push(value) {
+        if (this.done)
+            return;
+        if (this.resolve) {
+            const r = this.resolve;
+            this.resolve = null;
+            r({ value, done: false });
+        }
+        else {
+            this.queue.push(value);
+        }
+    }
+    close() {
+        this.done = true;
+        if (this.resolve) {
+            const r = this.resolve;
+            this.resolve = null;
+            r({ value: undefined, done: true });
+        }
+    }
+    [Symbol.asyncIterator]() {
+        return {
+            next: () => {
+                if (this.queue.length > 0) {
+                    return Promise.resolve({ value: this.queue.shift(), done: false });
+                }
+                if (this.done) {
+                    return Promise.resolve({ value: undefined, done: true });
+                }
+                return new Promise((resolve) => {
+                    this.resolve = resolve;
+                });
+            },
+        };
+    }
+}

package/dist/router.d.ts

@@ -0,0 +1,8 @@
+import { Hono } from "hono";
+import type { SessionManager } from "./session.js";
+import { type MessageTranslator } from "./translator.js";
+export declare function createAgentRouter<TCtx>(config: {
+    sessions: SessionManager<TCtx>;
+    translator: MessageTranslator<TCtx>;
+    basePath?: string;
+}): Hono;

package/dist/router.js

@@ -0,0 +1,67 @@
+import { Hono } from "hono";
+import { cors } from "hono/cors";
+import { sseEncode, streamSession } from "./translator.js";
+export function createAgentRouter(config) {
+    const { sessions, translator, basePath = "/api" } = config;
+    const app = new Hono();
+    app.use(`${basePath}/*`, cors({ origin: "*" }));
+    app.post(`${basePath}/sessions`, (c) => {
+        const session = sessions.create();
+        return c.json({ sessionId: session.id });
+    });
+    app.post(`${basePath}/sessions/:id/messages`, async (c) => {
+        const session = sessions.get(c.req.param("id"));
+        if (!session)
+            return c.json({ error: "Session not found" }, 404);
+        const body = await c.req.json();
+        if (!body.text?.trim())
+            return c.json({ error: "Message text required" }, 400);
+        session.pushMessage(body.text.trim());
+        return c.json({ ok: true });
+    });
+    app.get(`${basePath}/sessions/:id/events`, (c) => {
+        const session = sessions.get(c.req.param("id"));
+        if (!session)
+            return c.json({ error: "Session not found" }, 404);
+        const stream = new ReadableStream({
+            async start(controller) {
+                const encoder = new TextEncoder();
+                try {
+                    for await (const evt of streamSession(session, translator)) {
+                        controller.enqueue(encoder.encode(sseEncode(evt)));
+                    }
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : "Unknown error";
+                    controller.enqueue(encoder.encode(sseEncode({ event: "error", data: JSON.stringify({ message }) })));
+                }
+                finally {
+                    controller.close();
+                }
+            },
+        });
+        return new Response(stream, {
+            headers: {
+                "Content-Type": "text/event-stream",
+                "Cache-Control": "no-cache",
+                Connection: "keep-alive",
+            },
+        });
+    });
+    app.post(`${basePath}/sessions/:id/permissions`, async (c) => {
+        const session = sessions.get(c.req.param("id"));
+        if (!session)
+            return c.json({ error: "Session not found" }, 404);
+        const body = await c.req.json();
+        if (!body.requestId || !body.kind) {
+            return c.json({ error: "Invalid permission response" }, 400);
+        }
+        const resolved = session.permissionGate.respond(body);
+        if (!resolved) {
+            return c.json({ error: "No pending request with this ID" }, 404);
+        }
+        session.lastActivityAt = Date.now();
+        return c.json({ ok: true });
+    });
+    return app;
+}

package/dist/session.d.ts

@@ -0,0 +1,40 @@
+import { query } from "@anthropic-ai/claude-agent-sdk";
+import { PermissionGate } from "./permission-gate.js";
+type SDKMessage = ReturnType<typeof query> extends AsyncGenerator<infer T> ? T : never;
+export interface SessionInit<TCtx> {
+    context: TCtx;
+    model: string;
+    systemPrompt: string;
+    mcpServers?: Record<string, unknown>;
+    tools?: unknown[];
+    allowedTools?: string[];
+    maxTurns?: number;
+    permissionMode?: "default" | "acceptEdits" | "plan" | "bypassPermissions";
+    thinking?: {
+        type: "enabled";
+        budgetTokens: number;
+    } | {
+        type: "disabled";
+    };
+}
+export interface Session<TCtx> {
+    id: string;
+    context: TCtx;
+    pushMessage(text: string): void;
+    messageIterator: AsyncIterable<SDKMessage>;
+    permissionGate: PermissionGate;
+    abort(): void;
+    createdAt: number;
+    lastActivityAt: number;
+}
+export declare class SessionManager<TCtx> {
+    private sessions;
+    private factory;
+    private idleTimeoutMs;
+    constructor(factory: () => SessionInit<TCtx>, idleTimeoutMs?: number);
+    create(): Session<TCtx>;
+    get(id: string): Session<TCtx> | undefined;
+    delete(id: string): void;
+    cleanup(): void;
+}
+export {};

package/dist/session.js

@@ -0,0 +1,117 @@
+import { query } from "@anthropic-ai/claude-agent-sdk";
+import { PermissionGate } from "./permission-gate.js";
+import { PushChannel } from "./push-channel.js";
+function userMessage(content) {
+    return {
+        type: "user",
+        message: { role: "user", content },
+        parent_tool_use_id: null,
+        session_id: "",
+    };
+}
+const DEFAULT_IDLE_TIMEOUT_MS = 30 * 60 * 1000;
+export class SessionManager {
+    sessions = new Map();
+    factory;
+    idleTimeoutMs;
+    constructor(factory, idleTimeoutMs) {
+        this.factory = factory;
+        this.idleTimeoutMs = idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS;
+    }
+    create() {
+        const id = crypto.randomUUID();
+        const init = this.factory();
+        const channel = new PushChannel();
+        const abortController = new AbortController();
+        const permissionGate = new PermissionGate();
+        const permissionMode = init.permissionMode ?? "bypassPermissions";
+        const isBypass = permissionMode === "bypassPermissions";
+        const canUseTool = isBypass
+            ? undefined
+            : async (toolName, input, options) => {
+                const requestId = crypto.randomUUID();
+                if (toolName === "AskUserQuestion") {
+                    const questions = (input.questions ?? []);
+                    const response = await permissionGate.request({
+                        kind: "user_question",
+                        requestId,
+                        questions,
+                    });
+                    if (response.kind === "user_question") {
+                        return {
+                            behavior: "allow",
+                            updatedInput: { ...input, answers: response.answers },
+                        };
+                    }
+                    return { behavior: "deny", message: "Cancelled" };
+                }
+                const response = await permissionGate.request({
+                    kind: "tool_approval",
+                    requestId,
+                    toolName,
+                    toolUseId: options.toolUseID,
+                    input,
+                    description: input.description,
+                });
+                if (response.kind === "tool_approval" && response.behavior === "allow") {
+                    return { behavior: "allow", updatedInput: input };
+                }
+                const message = response.kind === "tool_approval" ? (response.message ?? "Denied by user") : "Denied";
+                return { behavior: "deny", message };
+            };
+        const messageIterator = query({
+            prompt: channel,
+            options: {
+                systemPrompt: init.systemPrompt,
+                model: init.model,
+                tools: init.tools ?? [],
+                mcpServers: init.mcpServers,
+                allowedTools: init.allowedTools,
+                maxTurns: init.maxTurns ?? 200,
+                permissionMode,
+                ...(isBypass ? { allowDangerouslySkipPermissions: true } : {}),
+                includePartialMessages: true,
+                abortController,
+                ...(canUseTool ? { canUseTool } : {}),
+                ...(init.thinking ? { thinking: init.thinking } : {}),
+            },
+        });
+        const session = {
+            id,
+            context: init.context,
+            pushMessage: (text) => {
+                session.lastActivityAt = Date.now();
+                channel.push(userMessage(text));
+            },
+            messageIterator,
+            permissionGate,
+            abort: () => {
+                permissionGate.cancelAll("Session aborted");
+                abortController.abort();
+            },
+            createdAt: Date.now(),
+            lastActivityAt: Date.now(),
+        };
+        this.sessions.set(id, session);
+        return session;
+    }
+    get(id) {
+        return this.sessions.get(id);
+    }
+    delete(id) {
+        const session = this.sessions.get(id);
+        if (session) {
+            session.abort();
+            this.sessions.delete(id);
+        }
+    }
+    cleanup() {
+        const now = Date.now();
+        for (const [id, session] of this.sessions) {
+            if (now - session.lastActivityAt > this.idleTimeoutMs) {
+                session.abort();
+                this.sessions.delete(id);
+            }
+        }
+    }
+}

package/dist/translator.d.ts

@@ -0,0 +1,15 @@
+import type { CustomEvent, SSEEvent } from "@neeter/types";
+import type { Session } from "./session.js";
+export interface TranslatorConfig<TCtx> {
+    onToolResult?: (toolName: string, result: string, session: Session<TCtx>) => CustomEvent[];
+}
+export declare class MessageTranslator<TCtx> {
+    private config;
+    private toolNames;
+    private hadStreamThinking;
+    constructor(config?: TranslatorConfig<TCtx>);
+    translate(message: Record<string, unknown>, session: Session<TCtx>): SSEEvent[];
+    private lastToolId;
+}
+export declare function sseEncode(evt: SSEEvent): string;
+export declare function streamSession<TCtx>(session: Session<TCtx>, translator: MessageTranslator<TCtx>): AsyncGenerator<SSEEvent>;

package/dist/translator.js

@@ -0,0 +1,236 @@
+import { PushChannel } from "./push-channel.js";
+export class MessageTranslator {
+    config;
+    toolNames = new Map();
+    hadStreamThinking = false;
+    constructor(config) {
+        this.config = config ?? {};
+    }
+    translate(message, session) {
+        const events = [];
+        const type = message.type;
+        switch (type) {
+            case "stream_event": {
+                if (!("event" in message))
+                    break;
+                const event = message.event;
+                switch (event.type) {
+                    case "message_start": {
+                        this.hadStreamThinking = false;
+                        events.push({ event: "message_start", data: "{}" });
+                        break;
+                    }
+                    case "content_block_start": {
+                        const block = event.content_block;
+                        switch (block?.type) {
+                            case "tool_use":
+                            case "server_tool_use": {
+                                const id = block.id;
+                                const name = block.name;
+                                this.toolNames.set(id, name);
+                                events.push({
+                                    event: "tool_start",
+                                    data: JSON.stringify({ id, name }),
+                                });
+                                break;
+                            }
+                            case "thinking": {
+                                events.push({ event: "thinking_start", data: "{}" });
+                                break;
+                            }
+                            case "web_search_tool_result": {
+                                const toolUseId = block.tool_use_id;
+                                const toolName = this.toolNames.get(toolUseId);
+                                const result = JSON.stringify(block.content);
+                                events.push({
+                                    event: "tool_result",
+                                    data: JSON.stringify({ toolUseId, result }),
+                                });
+                                if (this.config.onToolResult && toolName) {
+                                    for (const c of this.config.onToolResult(toolName, result, session)) {
+                                        events.push({ event: "custom", data: JSON.stringify(c) });
+                                    }
+                                }
+                                break;
+                            }
+                        }
+                        break;
+                    }
+                    case "content_block_delta": {
+                        const delta = event.delta;
+                        if (delta.type === "thinking_delta" && typeof delta.thinking === "string") {
+                            this.hadStreamThinking = true;
+                            events.push({
+                                event: "thinking_delta",
+                                data: JSON.stringify({ text: delta.thinking }),
+                            });
+                        }
+                        else if (delta.type === "text_delta" && typeof delta.text === "string") {
+                            events.push({
+                                event: "text_delta",
+                                data: JSON.stringify({ text: delta.text }),
+                            });
+                        }
+                        else if (delta.type === "input_json_delta" &&
+                            typeof delta.partial_json === "string") {
+                            const id = this.lastToolId();
+                            if (id) {
+                                events.push({
+                                    event: "tool_input_delta",
+                                    data: JSON.stringify({ id, partialJson: delta.partial_json }),
+                                });
+                            }
+                        }
+                        break;
+                    }
+                }
+                break;
+            }
+            case "assistant": {
+                const msg = message.message;
+                if (msg?.content) {
+                    for (const block of msg.content) {
+                        switch (block.type) {
+                            case "thinking": {
+                                if (!this.hadStreamThinking && typeof block.thinking === "string") {
+                                    events.push({
+                                        event: "thinking_delta",
+                                        data: JSON.stringify({ text: block.thinking }),
+                                    });
+                                }
+                                break;
+                            }
+                            case "tool_use":
+                            case "server_tool_use": {
+                                const name = block.name;
+                                const id = block.id;
+                                this.toolNames.set(id, name);
+                                events.push({
+                                    event: "tool_call",
+                                    data: JSON.stringify({ id, name, input: block.input }),
+                                });
+                                break;
+                            }
+                            case "web_search_tool_result": {
+                                const toolUseId = block.tool_use_id;
+                                const toolName = this.toolNames.get(toolUseId);
+                                const result = JSON.stringify(block.content);
+                                events.push({
+                                    event: "tool_result",
+                                    data: JSON.stringify({ toolUseId, result }),
+                                });
+                                if (this.config.onToolResult && toolName) {
+                                    for (const c of this.config.onToolResult(toolName, result, session)) {
+                                        events.push({ event: "custom", data: JSON.stringify(c) });
+                                    }
+                                }
+                                break;
+                            }
+                        }
+                    }
+                }
+                break;
+            }
+            case "user": {
+                const msg = message.message;
+                if (Array.isArray(msg?.content)) {
+                    for (const block of msg.content) {
+                        if (block.type === "tool_result") {
+                            const text = extractToolResultText(block);
+                            const toolName = this.toolNames.get(block.tool_use_id);
+                            events.push({
+                                event: "tool_result",
+                                data: JSON.stringify({ toolUseId: block.tool_use_id, result: text }),
+                            });
+                            if (this.config.onToolResult && toolName) {
+                                for (const c of this.config.onToolResult(toolName, text, session)) {
+                                    events.push({ event: "custom", data: JSON.stringify(c) });
+                                }
+                            }
+                        }
+                    }
+                }
+                break;
+            }
+            case "tool_progress": {
+                events.push({
+                    event: "tool_progress",
+                    data: JSON.stringify({
+                        toolName: message.tool_name,
+                        elapsed: message.elapsed_time_seconds,
+                    }),
+                });
+                break;
+            }
+            case "result": {
+                if (message.subtype === "success") {
+                    events.push({
+                        event: "turn_complete",
+                        data: JSON.stringify({
+                            numTurns: message.num_turns ?? 0,
+                            cost: message.total_cost_usd ?? 0,
+                        }),
+                    });
+                }
+                else {
+                    events.push({
+                        event: "session_error",
+                        data: JSON.stringify({ subtype: message.subtype }),
+                    });
+                }
+                break;
+            }
+        }
+        return events;
+    }
+    lastToolId() {
+        const entries = [...this.toolNames.entries()];
+        return entries.length > 0 ? entries[entries.length - 1][0] : undefined;
+    }
+}
+export function sseEncode(evt) {
+    return `event: ${evt.event}\ndata: ${evt.data}\n\n`;
+}
+export async function* streamSession(session, translator) {
+    const output = new PushChannel();
+    const unsubscribe = session.permissionGate.onRequest((request) => {
+        output.push({ event: "permission_request", data: JSON.stringify(request) });
+    });
+    for (const pending of session.permissionGate.getPending()) {
+        yield { event: "permission_request", data: JSON.stringify(pending) };
+    }
+    const driveMessages = async () => {
+        try {
+            for await (const message of session.messageIterator) {
+                const events = translator.translate(message, session);
+                for (const evt of events) {
+                    output.push(evt);
+                }
+            }
+        }
+        finally {
+            unsubscribe();
+            output.close();
+        }
+    };
+    driveMessages();
+    for await (const evt of output) {
+        yield evt;
+    }
+}
+function extractToolResultText(block) {
+    const content = block.content;
+    if (typeof content === "string")
+        return content;
+    if (Array.isArray(content)) {
+        const textParts = content
+            .filter((p) => p.type === "text" && typeof p.text === "string")
+            .map((p) => p.text);
+        if (textParts.length > 0)
+            return textParts.join("");
+        // Non-text content blocks (e.g. web_search_tool_result) — serialize so
+        // downstream consumers (widgets, onToolResult) can still parse the data.
+        return JSON.stringify(content);
+    }
+    return "";
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@neeter/server",
+  "version": "0.6.0",
+  "description": "Hono server toolkit for building chat UIs on top of the Claude Agent SDK",
+  "license": "MIT",
+  "author": "Dan Leeper",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/quantumleeps/neeter.git",
+    "directory": "packages/server"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@neeter/types": "0.6.0"
+  },
+  "peerDependencies": {
+    "@anthropic-ai/claude-agent-sdk": ">=0.2.0",
+    "hono": ">=4.0.0"
+  },
+  "devDependencies": {
+    "@anthropic-ai/claude-agent-sdk": "latest",
+    "hono": "^4.11.9"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  }
+}