@cuylabs/agent-server 0.10.0

package/docs/README.md

@@ -0,0 +1,22 @@
+# Agent Server Docs
+
+- [Architecture](./architecture.md)
+- [Protocol](./protocol.md)
+- [Clients And Transports](./clients-and-transports.md)
+- [Plugins And Boundaries](./plugins-and-boundaries.md)
+- [Runtime And Dapr](./runtime-and-dapr.md)
+
+## Source map
+
+- `src/protocol/contracts.ts`
+  - capability contract, shared types, adapter surface
+- `src/protocol/wire.ts`
+  - request / response / notification wire schema (29 methods)
+- `src/runtime/in-process-server.ts`
+  - session and turn authority
+- `src/runtime/interactive-handlers.ts`
+  - `InteractiveRequestBridge` and approval/human-input server handlers
+- `src/client/`
+  - in-process and remote client facades, `streamTurn` helper
+- `src/transport/`
+  - stdio, websocket, and RPC connection plumbing

package/docs/architecture.md

@@ -0,0 +1,61 @@
+# Architecture
+
+`@cuylabs/agent-server` is the host layer above the agent framework.
+
+It does not replace the lower packages:
+
+- `@cuylabs/agent-core`
+  - agent execution, sessions, tools, middleware, plugins
+- `@cuylabs/agent-runtime`
+  - scheduling and orchestration abstractions
+- `@cuylabs/agent-runtime-dapr`
+  - Dapr-backed durability and hosted workflows
+- `@cuylabs/agent-server`
+  - live session and turn ownership for clients
+
+## Role
+
+The server owns:
+
+- session listing, creation, reading, deletion, and branching
+- turn start, wait, interrupt, steering, and follow-up queuing
+- follow-up management (list, get, resolve/discard)
+- live notification fanout
+- approval request routing
+- human input request routing
+- startup and workspace summary snapshots
+- capability-gated agent affordances such as model inspection, model switching, and runtime status
+
+Clients own:
+
+- user input
+- rendering
+- command routing in the host app
+- reconnect behavior and transport choice
+
+## Public surface
+
+The package is intentionally split by role:
+
+- `src/types.ts`
+  - protocol contracts and wire types
+- `src/server.ts`
+  - server-side runtime, transport helpers, and interactive request handlers
+- `src/client.ts`
+  - client-side facades and `streamTurn` helper
+
+That matches the package entrypoints exported from `src/index.ts`.
+
+## Current implementation
+
+The current runtime authority is `InProcessAgentServer` in `src/runtime/in-process-server.ts`.
+
+It tracks:
+
+- active turns
+- session runtime state
+- pending approval/input requests
+- queued follow-up records
+- subscribers for live notifications
+
+Transports do not own the agent loop. They only expose the same server surface over different connections.

package/docs/clients-and-transports.md

@@ -0,0 +1,92 @@
+# Clients And Transports
+
+The client surface is split into two layers:
+
+- `src/client/`
+  - client facades
+- `src/transport/`
+  - connection implementations
+
+## Clients
+
+`InProcessAgentServerClient`
+
+- talks directly to an in-memory `AgentServer`
+- used by the CLI in embedded mode
+- good for local execution and tests
+
+`RemoteAgentServerClient`
+
+- speaks the wire protocol over a transport
+- caches turn notifications for inspection
+- handles request timeouts and reconnect-sensitive state
+
+### Helpers
+
+`streamTurn(client, sessionId, message, options?)`
+
+- async generator that starts a turn, subscribes to events, and yields `AgentEvent`s
+- the primary streaming utility for consuming agent output
+
+`createInProcessAgentServer(agent)` / `createInProcessAgentServerClient(agent)`
+
+- convenience factories that wire `createAgentServerAdapter` + server/client construction in one call
+
+## Transports
+
+### Stdio
+
+Defined in `src/transport/stdio.ts`.
+
+Use it when:
+
+- a parent process wants to spawn `cuylabs server`
+- exactly one child client needs the connection
+- pipes are simpler than sockets
+
+Characteristics:
+
+- `protocol.transport = "stdio"`
+- `reconnectable = false`
+- `multiClient = false`
+- stdout is reserved for the wire protocol
+
+API:
+
+- `attachAgentServerStdio(server, options?)` — server side
+- `connectStdioAgentServerClient(options)` — spawns a child process and returns a connected `RemoteAgentServerClient`
+
+### WebSocket
+
+Defined in `src/transport/websocket.ts`.
+
+Use it when:
+
+- external clients need reconnectable access
+- more than one client may connect over time
+- a local service should stay up independently of a single shell
+
+Characteristics:
+
+- `protocol.transport = "websocket"`
+- `reconnectable = true`
+- `multiClient = true`
+
+API:
+
+- `startAgentServerWebSocketServer(server, options)` — server side. Options: `{ port?, host?, httpServer? }`. The `httpServer` option lets you share a port with another HTTP surface (e.g. `agent-runtime-dapr`'s REST/SSE handler).
+- `connectWebSocketAgentServerClient(options)` — client side. Options: `{ url, headers?, requestTimeoutMs? }`.
+
+## RPC connection
+
+`AgentServerRpcConnection` in `src/transport/rpc-connection.ts` adapts an `AgentServer` to any envelope-based transport.
+
+It is responsible for:
+
+- per-connection capability overrides
+- dispatching wire requests to the server
+- forwarding notifications to subscribers
+
+Also exports `matchesNotificationSubscription(notification, options?)` — a utility for filtering notifications by turn/session/type.
+
+That keeps transport code thin and keeps request routing in one place.

package/docs/plugins-and-boundaries.md

@@ -0,0 +1,41 @@
+# Plugins And Boundaries
+
+`@cuylabs/agent-server` does not introduce a second plugin model.
+
+## What stays server-side
+
+`agent-core` plugins still own:
+
+- tools
+- middleware
+- prompt sections
+- lifecycle hooks
+- plugin commands
+
+That logic runs where the agent runs.
+
+## What clients should not do
+
+Clients should not expect plugins to:
+
+- render custom TUI widgets
+- render custom web components
+- import host UI internals
+- manipulate renderer state directly
+
+`agent-server` keeps the plugin contract headless.
+
+## Plugin commands
+
+The server does expose plugin commands through the contract:
+
+- `listPluginCommands()`
+- `executePluginCommand(name, args)`
+
+That lets a host discover and route plugin-defined commands without duplicating plugin logic in every client.
+
+## Future UI extensions
+
+If the project later needs renderer-specific extensions, they should be introduced as a separate client-layer API.
+
+Do not expand `agent-core` plugins into a mixed server-plus-UI contract.

package/docs/protocol.md

@@ -0,0 +1,111 @@
+# Protocol
+
+The shared contract lives in `src/protocol/contracts.ts`.
+
+## Core concepts
+
+- `session`
+  - persisted conversation state backed by `agent-core` storage
+- `turn`
+  - one user message plus the streamed agent work that follows
+- `notification`
+  - a server-emitted update such as `turn/event`, `turn/completed`, or `input/request`
+
+## Capabilities
+
+Clients inspect `getCapabilities()` first instead of assuming a feature exists.
+
+The capability sections are:
+
+- `protocol`
+  - protocol version, transport kind, reconnectability, multi-client support
+- `sessions`
+  - persistent storage, list, create, read, delete, branch
+- `turns`
+  - start, wait, interrupt, steer, follow-up, follow-up management, event streaming, concurrent turns per session
+- `interactive`
+  - approval requests, human input requests
+- `runtime`
+  - execution mode, orchestration backend, durability mode, Dapr availability
+- `agent`
+  - workspace summary, runtime status, model inspection, model switching, tool/skill/sub-agent inventory, compact, undo, diff
+- `plugins`
+  - headless plugin behavior and plugin command support
+
+## Workspace summary
+
+`getWorkspaceSummary()` gives clients a startup snapshot without forcing them to stitch together:
+
+- model label and switchable flag
+- tool count
+- skill count
+- sub-agent count
+- session count
+- workspace cwd
+
+That is what the CLI welcome state now uses by default.
+
+## Wire contract
+
+The transport-level request and response types live in `src/protocol/wire.ts`.
+
+Important methods include:
+
+### Session & workspace
+
+- `initialize`
+- `capabilities/get`
+- `workspace/summary`
+- `session/list`
+- `session/create`
+- `session/read`
+- `session/delete`
+- `session/branch`
+- `session/status`
+- `session/compact`
+- `session/undo`
+- `session/diff`
+
+### Agent inspection
+
+- `agent/model/get`
+- `agent/model/switch`
+- `agent/tools`
+- `agent/skills`
+- `agent/sub-agents`
+
+### Turn lifecycle
+
+- `turn/start`
+- `turn/get`
+- `turn/wait`
+- `turn/interrupt`
+- `turn/steer`
+- `turn/follow-up`
+
+### Follow-up management
+
+- `follow-up/list`
+- `follow-up/get`
+- `follow-up/resolve`
+
+### Interactive
+
+- `input/respond`
+
+For human-input routing in direct mode, the server adapter exposes
+`interactive.humanRequests = true` only when the hosted agent has:
+
+- a configured human-input controller
+- at least one human-input-capable tool
+
+That keeps protocol capability reporting aligned with the actual request
+surface instead of assuming every direct agent can answer human-input
+requests.
+
+### Plugins
+
+- `plugin-command/list`
+- `plugin-command/execute`
+
+Notifications are streamed independently of request responses.

package/docs/runtime-and-dapr.md

@@ -0,0 +1,41 @@
+# Runtime And Dapr
+
+`agent-server` is the client-facing host layer.
+
+It is not the same thing as `agent-runtime` or `agent-runtime-dapr`.
+
+## Responsibilities
+
+`agent-server`
+
+- owns session and turn APIs
+- owns subscriptions and live notifications
+- owns reconnect semantics for clients
+
+`agent-runtime`
+
+- defines orchestration abstractions
+- schedules and dispatches work
+
+`agent-runtime-dapr`
+
+- provides Dapr-backed durability
+- provides workflow hosting and checkpoints
+- can back some turns or workloads behind the same server-facing contract
+
+## Why the separation matters
+
+Clients should not need to know whether a turn is:
+
+- direct and local
+- orchestrated through `agent-runtime`
+- delegated to `agent-runtime-dapr`
+
+They only need to inspect the exposed capabilities and interact with the same session and turn surface.
+
+That is why the capability contract includes:
+
+- execution mode
+- orchestration backend
+- durability mode
+- Dapr availability flags

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@cuylabs/agent-server",
+  "version": "0.10.0",
+  "description": "Transport-neutral local server for @cuylabs/agent-core sessions, turns, and streamed events",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "docs",
+    "README.md"
+  ],
+  "dependencies": {
+    "ws": "^8.19.0",
+    "@cuylabs/agent-core": "^0.10.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.0.18"
+  },
+  "keywords": [
+    "agent",
+    "app-server",
+    "sessions",
+    "turns",
+    "streaming"
+  ],
+  "author": "cuylabs",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cuylabs-ai/agents-ts.git",
+    "directory": "packages/agent-server"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts --format esm --dts --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
+}