@neeter/server 0.8.0 → 0.9.0

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

@@ -1,10 +1,34 @@
 import type { HookCallbackMatcher } from "@anthropic-ai/claude-agent-sdk";
+export interface SandboxHookOptions {
+    /**
+     * Allow Bash tool calls through the sandbox hook (default: `false`).
+     *
+     * Bash commands can reference arbitrary filesystem paths via subshells,
+     * variable expansion, redirects, and other shell features that can't be
+     * reliably inspected. When `false`, all Bash calls are blocked.
+     *
+     * If you need Bash access inside a sandbox, set this to `true` and use
+     * OS-level isolation instead: containers with `--network none` and a
+     * read-only filesystem, `@anthropic-ai/sandbox-runtime`, or VMs.
+     *
+     * @see https://platform.claude.com/docs/en/agent-sdk/secure-deployment
+     */
+    allowBash?: boolean;
+}
 /**
  * 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.
  *
+ * Bash is blocked by default because shell commands can reference paths outside the
+ * sandbox in ways that can't be reliably detected (subshells, variable expansion,
+ * redirects, backticks). To sandbox Bash, use OS-level isolation — containers,
+ * `@anthropic-ai/sandbox-runtime`, or VMs — and set `options.allowBash` to `true`.
+ *
+ * @see https://platform.claude.com/docs/en/agent-sdk/secure-deployment
+ *
  * @param sandboxDir - Absolute path to the sandbox directory (must already be resolved)
  * @param resolvePath - Path resolver function (e.g. `path.resolve` from `node:path`)
+ * @param options - Configuration options
  */
-export declare function createSandboxHook(sandboxDir: string, resolvePath: (...segments: string[]) => string): HookCallbackMatcher[];
+export declare function createSandboxHook(sandboxDir: string, resolvePath: (...segments: string[]) => string, options?: SandboxHookOptions): HookCallbackMatcher[];

package/dist/hooks.js

@@ -3,17 +3,35 @@
  * Inspects `file_path` and `path` fields in tool input and blocks any resolved path
  * that falls outside the given directory.
  *
+ * Bash is blocked by default because shell commands can reference paths outside the
+ * sandbox in ways that can't be reliably detected (subshells, variable expansion,
+ * redirects, backticks). To sandbox Bash, use OS-level isolation — containers,
+ * `@anthropic-ai/sandbox-runtime`, or VMs — and set `options.allowBash` to `true`.
+ *
+ * @see https://platform.claude.com/docs/en/agent-sdk/secure-deployment
+ *
  * @param sandboxDir - Absolute path to the sandbox directory (must already be resolved)
  * @param resolvePath - Path resolver function (e.g. `path.resolve` from `node:path`)
+ * @param options - Configuration options
  */
-export function createSandboxHook(sandboxDir, resolvePath) {
+export function createSandboxHook(sandboxDir, resolvePath, options) {
     const normalizedDir = resolvePath(sandboxDir);
+    const allowBash = options?.allowBash ?? false;
     return [
         {
             hooks: [
                 async (input) => {
                     if (input.hook_event_name !== "PreToolUse")
                         return {};
+                    const toolName = input.tool_name;
+                    if (toolName === "Bash" && !allowBash) {
+                        return {
+                            decision: "block",
+                            reason: "Bash is blocked in sandbox mode — shell commands can reference arbitrary paths. " +
+                                "Use allowBash with OS-level isolation (containers, sandbox-runtime) for Bash access. " +
+                                "See https://platform.claude.com/docs/en/agent-sdk/secure-deployment",
+                        };
+                    }
                     const toolInput = input.tool_input;
                     const filePath = (toolInput.file_path ?? toolInput.path);
                     if (!filePath)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neeter/server",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "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.8.0"
+    "@neeter/types": "0.9.0"
   },
   "peerDependencies": {
     "@anthropic-ai/claude-agent-sdk": ">=0.2.0",