@neeter/server 0.7.1 → 0.8.1

package/README.md

@@ -0,0 +1,81 @@
+# @neeter/server
+
+A Hono server toolkit that puts a browser UI on the [Claude Agent SDK](https://github.com/anthropics/claude-agent-sdk). Manages multi-turn sessions, translates SDK messages into named SSE events, and handles tool-approval permissions — so your React client gets a clean event stream out of the box.
+
+Part of the [neeter](https://github.com/quantumleeps/neeter) toolkit.
+
+## Install
+
+```bash
+pnpm add @neeter/server
+```
+
+Peer dependencies:
+
+```json
+{
+  "@anthropic-ai/claude-agent-sdk": ">=0.2.0",
+  "hono": ">=4.0.0"
+}
+```
+
+## Quick start
+
+```typescript
+import { Hono } from "hono";
+import { serve } from "@hono/node-server";
+import {
+  createAgentRouter,
+  SessionManager,
+  MessageTranslator,
+} from "@neeter/server";
+
+const sessions = new SessionManager(() => ({
+  context: {},
+  model: "claude-sonnet-4-5-20250929",
+  systemPrompt: "You are a helpful assistant.",
+  maxTurns: 50,
+}));
+
+const translator = new MessageTranslator();
+
+const app = new Hono();
+app.route("/", createAgentRouter({ sessions, translator }));
+
+serve({ fetch: app.fetch, port: 3000 });
+```
+
+This gives you five endpoints:
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/api/sessions` | Create a session |
+| `POST` | `/api/sessions/:id/messages` | Send a message |
+| `GET` | `/api/sessions/:id/events` | SSE event stream |
+| `POST` | `/api/sessions/:id/permissions` | Respond to a permission request |
+| `POST` | `/api/sessions/:id/abort` | Abort the current turn |
+
+## Key features
+
+- **Multi-turn sessions** — `SessionManager` + `PushChannel` let users send messages at any time, even while the agent is running.
+- **Named SSE events** — `MessageTranslator` reshapes the SDK's flat message stream into `text_delta`, `tool_start`, `tool_call`, `tool_result`, and more.
+- **Tool result hooks** — `onToolResult` lets you inspect what the agent did and emit structured custom events.
+- **Permission modes** — `bypassPermissions`, `default`, `acceptEdits`, or `plan` — with browser-side approval via `PermissionGate`.
+- **Extended thinking** — Pass `thinking: { type: "enabled", budgetTokens: N }` to stream chain-of-thought reasoning.
+- **Abort** — Cancel the current agent turn mid-stream.
+- **Sandbox hooks** — `createSandboxHook` restricts file operations to a directory.
+
+## Examples
+
+| Example | Description |
+|---------|-------------|
+| [basic-chat](https://github.com/quantumleeps/neeter/tree/main/examples/basic-chat) | Minimal server + client setup |
+| [live-preview](https://github.com/quantumleeps/neeter/tree/main/examples/live-preview) | Per-session sandboxes, custom events, abort |
+
+## Documentation
+
+See the [neeter README](https://github.com/quantumleeps/neeter#readme) for full API reference, session context examples, and permission configuration.
+
+## License
+
+MIT

package/dist/hooks.d.ts

@@ -0,0 +1,10 @@
+import type { HookCallbackMatcher } from "@anthropic-ai/claude-agent-sdk";
+/**
+ * Creates a PreToolUse hook that blocks file operations outside a sandbox directory.
+ * Inspects `file_path` and `path` fields in tool input and blocks any resolved path
+ * that falls outside the given directory.
+ *
+ * @param sandboxDir - Absolute path to the sandbox directory (must already be resolved)
+ * @param resolvePath - Path resolver function (e.g. `path.resolve` from `node:path`)
+ */
+export declare function createSandboxHook(sandboxDir: string, resolvePath: (...segments: string[]) => string): HookCallbackMatcher[];

package/dist/hooks.js

@@ -0,0 +1,30 @@
+/**
+ * Creates a PreToolUse hook that blocks file operations outside a sandbox directory.
+ * Inspects `file_path` and `path` fields in tool input and blocks any resolved path
+ * that falls outside the given directory.
+ *
+ * @param sandboxDir - Absolute path to the sandbox directory (must already be resolved)
+ * @param resolvePath - Path resolver function (e.g. `path.resolve` from `node:path`)
+ */
+export function createSandboxHook(sandboxDir, resolvePath) {
+    const normalizedDir = resolvePath(sandboxDir);
+    return [
+        {
+            hooks: [
+                async (input) => {
+                    if (input.hook_event_name !== "PreToolUse")
+                        return {};
+                    const toolInput = input.tool_input;
+                    const filePath = (toolInput.file_path ?? toolInput.path);
+                    if (!filePath)
+                        return {};
+                    const resolved = resolvePath(filePath);
+                    if (resolved !== normalizedDir && !resolved.startsWith(`${normalizedDir}/`)) {
+                        return { decision: "block", reason: "Access outside sandbox directory is not allowed" };
+                    }
+                    return {};
+                },
+            ],
+        },
+    ];
+}

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export type { CustomEvent, SSEEvent } from "@neeter/types";
+export { createSandboxHook } from "./hooks.js";
 export { PermissionGate } from "./permission-gate.js";
 export { PushChannel } from "./push-channel.js";
 export { createAgentRouter } from "./router.js";

package/dist/index.js

@@ -1,3 +1,4 @@
+export { createSandboxHook } from "./hooks.js";
 export { PermissionGate } from "./permission-gate.js";
 export { PushChannel } from "./push-channel.js";
 export { createAgentRouter } from "./router.js";

package/dist/router.js

@@ -63,5 +63,12 @@ export function createAgentRouter(config) {
         session.lastActivityAt = Date.now();
         return c.json({ ok: true });
     });
+    app.post(`${basePath}/sessions/:id/abort`, (c) => {
+        const session = sessions.get(c.req.param("id"));
+        if (!session)
+            return c.json({ error: "Session not found" }, 404);
+        session.abort();
+        return c.json({ ok: true });
+    });
     return app;
 }

package/dist/session.d.ts

@@ -1,4 +1,4 @@
-import { query } from "@anthropic-ai/claude-agent-sdk";
+import { type HookCallbackMatcher, type HookEvent, 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> {
@@ -8,7 +8,9 @@ export interface SessionInit<TCtx> {
     mcpServers?: Record<string, unknown>;
     tools?: unknown[];
     allowedTools?: string[];
+    disallowedTools?: string[];
     maxTurns?: number;
+    cwd?: string;
     permissionMode?: "default" | "acceptEdits" | "plan" | "bypassPermissions";
     thinking?: {
         type: "enabled";
@@ -16,6 +18,7 @@ export interface SessionInit<TCtx> {
     } | {
         type: "disabled";
     };
+    hooks?: Partial<Record<HookEvent, HookCallbackMatcher[]>>;
 }
 export interface Session<TCtx> {
     id: string;

package/dist/session.js

@@ -1,4 +1,4 @@
-import { query } from "@anthropic-ai/claude-agent-sdk";
+import { query, } from "@anthropic-ai/claude-agent-sdk";
 import { PermissionGate } from "./permission-gate.js";
 import { PushChannel } from "./push-channel.js";
 function userMessage(content) {
@@ -74,6 +74,9 @@ export class SessionManager {
                 abortController,
                 ...(canUseTool ? { canUseTool } : {}),
                 ...(init.thinking ? { thinking: init.thinking } : {}),
+                ...(init.cwd ? { cwd: init.cwd } : {}),
+                ...(init.disallowedTools ? { disallowedTools: init.disallowedTools } : {}),
+                ...(init.hooks ? { hooks: init.hooks } : {}),
             },
         });
         const session = {

package/dist/translator.js

@@ -208,6 +208,9 @@ export async function* streamSession(session, translator) {
                 }
             }
         }
+        catch {
+            // Session was aborted or SDK threw — fall through to close the channel
+        }
         finally {
             unsubscribe();
             output.close();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neeter/server",
-  "version": "0.7.1",
+  "version": "0.8.1",
   "description": "Hono server toolkit for building chat UIs on top of the Claude Agent SDK",
   "license": "MIT",
   "author": "Dan Leeper",
@@ -17,10 +17,11 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "dependencies": {
-    "@neeter/types": "0.7.1"
+    "@neeter/types": "0.8.1"
   },
   "peerDependencies": {
     "@anthropic-ai/claude-agent-sdk": ">=0.2.0",
@@ -28,6 +29,7 @@
   },
   "devDependencies": {
     "@anthropic-ai/claude-agent-sdk": "latest",
+    "@types/node": "^22.19.11",
     "hono": "^4.11.9"
   },
   "scripts": {