Release notes · Agent Server

Agent Server Release Notes

Changelog for @cognipeer/agent-server. For usage, see the Agent Server documentation.

All notable changes to @cognipeer/agent-server.

[0.4.0] - 2026-10

Clients can now choose a model on each message request, and the server advertises which model keys an agent allows. Invalid model keys are now rejected with a dedicated model_not_allowed error, so clients that opt into the new field should validate what they send and handle the new response.

• Message requests can include a model field to choose the model for that turn.
• Agent information now advertises the model keys a client may choose from.
• Requests with an unsupported model key are rejected with model_not_allowed.
• Clients that want per-message model selection should update their request payloads to send the new field.
• Clients should also handle the new validation error response when a model key is not allowed.

[0.3.0] - 2026-10-10

Human-in-the-loop, runs that outlive the request, files the agent reads, and one tested storage contract. An agent that never pauses behaves as before, but a few behaviours changed (mostly security hardening and storage parity): read Upgrading to 0.3.0 before you upgrade a running server.

Added

• Approvals and questions. A turn can end with status: "requires_action" and a list of pendingActions (tool approvals, user questions and client tools). POST /conversations/:id/actions/:actionId resolves one and carries the turn on, streamed or as JSON. New stream.action_required and stream.action_resolved events, pendingActionPolicy, remembered tools, edited arguments checked against the tool's schema, deadlines (hitl.timeoutMinutes, hitl.onTimeout), hitl.authorizeResolve and a durable record on the message. See Approvals & Questions.
• Detached runs, cancel and an event log. A turn is a run that no longer depends on the HTTP request that started it. POST /conversations/:id/cancel stops it, GET /conversations/:id/events/stream lets a client reattach after a reload, seq marks every stream.* frame, and a second message while a turn runs is 409 conversation_busy. Leases and a recovery sweep close a run whose server died as run_interrupted. See Runs, Cancel & Reattach.
• Usage and budgets. usage comes from the agent-sdk ledger, pricing(model) prices tokens, and budget: { maxCostUsd, onReach: "pause" | "stop" } limits a conversation (402 budget_reached, POST /conversations/:id/continue after a raise). See Usage & Budgets.
• Files the agent reads. The files server option and a per-agent override, raw-body uploads (POST /files?name=&conversationId=), fileIds on a message, inline documents and images by reference, PDF and Office extraction through @cognipeer/to-markdown, ownership, retention (files.retentionDays) and AgentInfo.capabilities.attachments. See Files.
• Host-backed agents. server.registerHostAgent({ info, invoke, resolveAction?, cancel? }) serves an agent whose work runs in the host's own backend. See Host-backed Agents.
• Chat experience. Regenerate and edit, pinning, bulk delete, per-agent title generation, feedback, export (md, json, html, pdf), welcome text and starters published through AgentInfo.metadata, and a rateLimit hook. See Chat Experience.
• Embedding. Per-request bearer auth through resolveContext, CORS that allows Last-Event-ID, and body limits that follow the largest file an agent accepts. See Embedding & Limits.
• Paged history on GET /conversations/:id (limit, before, after, order), tasks that run in a conversation, server.getRoutes(), allowAnonymousList, the PendingAction.argsSchema of a tool approval, and the Fastify option uploadBodyLimit.
• A storage provider contract suite run against memory, SQLite, MongoDB and PostgreSQL with real databases, StorageProvider.capabilities(), limits.maxStateBytes, GridFS for MongoDB file content and StorageLimitError (413).
• A runnable standalone example (examples/standalone) with a scripted model, so it needs no API key.

Changed

• Listing needs a user. GET /conversations and GET /tasks answer 401 identity_required to a request that names nobody, unless the server sets allowAnonymousList: true.
• The identity the server established wins. A ?userId= or a userId in a create body is ignored when token auth, auth.resolveUserId or resolveContext named the user.
• createJWTAuthProvider verifies the signature (HS, RS and ES algorithms), exp, nbf, iss and aud, and throws without a secret. createAgentServer throws when auth.enabled is true and no provider is given. Generated tokens are 256 random bits, kept as a hash.
• A disconnect no longer cancels a turn. Call POST /conversations/:id/cancel to stop one.
• Files expire after 30 days unless files.retentionDays is 0, are visible only to the uploader, and attach only to the conversation they were uploaded to. limits.maxFiles now counts the files one message attaches.
• GET /conversations/:id returns the newest page of 100 messages instead of the first 100.
• SQLite and PostgreSQL run a one-time schema upgrade on connect (back up first); MongoDB adds collections and indexes.
• All four built-in storage providers now behave the same way when they read, order, delete and save records (see the migration page for the list).

Fixed

• The agent received only the first 100 messages of a conversation, so after about 50 turns the newest message never reached the model.
• MongoDB returned file content as a BSON Binary, failed uploads over 16 MiB, and stored left-out fields as null. PostgreSQL returned message text that is valid JSON as a number, boolean or object.
• A turn that the budget cut short stays resumable after the budget is raised, and Stop is recorded as cancelled on every path.
• Uploads that arrive together can no longer put more than files.maxFiles files into a conversation.

[0.2.0] - 2026-10-09

Request context, per-request agents and more ways to mount the server. All changes are additive; existing configurations keep working unchanged. See Request Context & Tenancy.

Added

• Request context. resolveContext(req) returns a RequestContext (user plus arbitrary data) or null (401). The context reaches dynamic agent resolvers, custom handlers, SDK agents, auth.resolveUserId and every storage call, and is readable anywhere in a request through getRequestContext().
• Dynamic agents. config.agents accepts a function resolved per request, with server.getAgentsFor(ctx) and getAgentFor(id, ctx). An agent that is not served to the request answers 404.
• Node handler. createNodeHandler(server, { basePath }) serves the API on raw IncomingMessage and ServerResponse (also @cognipeer/agent-server/node).
• Fastify adapter. @cognipeer/agent-server/fastify (createFastifyPlugin, mountOnFastify) mounts the server under a prefix that may contain parameters. See Fastify & Node HTTP.
• Storage context. Every StorageProvider method takes an optional trailing ctx so an external store can scope by tenant or user.
• maskServerErrors hides the message of any error that does not carry an explicit 4xx status.

Fixed

• With resolveContext, a conversation or task that carries no userId is refused (403) instead of being open to every authenticated caller.
• limit is capped at 200 and a negative or non-numeric offset becomes 0 before it reaches the storage provider.
• An SDK agent that returned its answer without streaming any text no longer ends the stream with an empty answer bubble.
• A streaming SDK agent that throws now ends the stream with a stream.error event instead of leaving it waiting.
• CommonJS consumers no longer fail with ERR_PACKAGE_PATH_NOT_EXPORTED, and plain { statusCode, code, message } errors keep their status instead of becoming a 500.

[0.1.6] - 2026-08-28

Added

• Node 24 CI and npm Trusted Publishing release workflows
• An entrypoint smoke test for server and in-memory storage construction

[0.1.5] - 2026-03-24

Fixed

• Prevented duplication of the final text chunk in Agent SDK streams
• Made the onEvent handler phase-aware to stop duplicate SSE tool_call events: start now emits stream.tool_call, success/error emit stream.tool_result, and skipped (tool limit reached) is suppressed — previously every tool call produced two stream.tool_call events, causing duplicate rendering in the chat UI

[0.1.4] - 2026-03-06

Added

• Chat Completions and Responses API providers for OpenAI-compatible endpoints and multi-turn conversations with built-in tools
• SQLite storage provider (via better-sqlite3), with migration logic for conversations, messages, files, tasks, and task results
• Automatic conversation title generation using LLM configuration

[0.1.3] - 2026-02-25

Fixed

• Ensured message content is always stringified in PostgresStorageProvider

Changed

• Enabled code splitting in the tsup build configuration

[0.1.2] - 2026-02-25

No distinct changes — published the same day as 0.1.0, 0.1.1, and 0.1.3 during the initial release's rapid-iteration burst. Git history jumps directly from the 0.1.1 to the 0.1.3 version bump, so no separate 0.1.2 commits could be identified; the fix and build change above are the actual delta.

[0.1.1] - 2026-02-25

Added

• Full Task system: types, storage-provider implementations (in-memory, MongoDB, PostgreSQL), API endpoints, execution logic, and Swagger/OpenAPI documentation
• Task comments feature with dedicated API endpoints and Swagger documentation
• Comprehensive Task system documentation

Changed

• Preserved tool-call information in message structure — SDK agent invocation now includes optional tool_calls, tool_call_id, and name fields, correctly mapped from prior messages
• Refactored event handling to use a shared helper for extracting tool event properties, with improved error logging
• Translated README to English and clarified installation instructions
• Added repository, homepage, and bugs metadata to package.json

Fixed

• Fixed a syntax error in the base storage provider
• Fixed callback status consistency (completed instead of complete)

[0.1.0] - 2025-01-01

Added

• Initial release
• createAgentServer factory function
• Express adapter with createExpressMiddleware
• Next.js adapter with createNextRouteHandlers
• PostgreSQL storage provider
• MongoDB storage provider
• In-memory storage provider
• Token-based authentication
• JWT authentication
• SSE streaming support
• File upload/download support
• Swagger UI integration
• OpenAPI spec generation
• SDK agent registration
• Custom agent handler support