@economic/agents 3.1.0 → 3.2.0

package/README.md

@@ -675,6 +675,24 @@ export class SupportAgent extends Agent<RequestContext, UserContext> {
 - **Requests without the caller's token,** such as an OAuth callback or a signed webhook, are refused unless `acceptsWithoutToken(request)` returns `true` for them. Check them another way.
 - **Any authenticator works:** `getAuthenticator(env)` can return your own `Authenticator`, such as one for a different identity provider.
 
+### Reading without chatting
+
+Return `false` from `canChat(userContext)` to let a user read their chats but not chat in them.
+
+- **Refused:** messages, approval answers, a client tool's result that would start another turn, and `run`. Nothing they send is kept.
+- **Still allowed:** reading the chat, rating messages, stopping a turn, and a client tool's result for the turn that's running. A running turn finishes.
+- **The client** is told in the `connected` frame (`canChat: false`), which `useChat` returns as `canChat`.
+- **When it's asked:** once per connection, when the user connects, so a change reaches them when they reconnect. An error counts as `false`. An override of `onConnect` must call `super.onConnect`.
+- **The connection** is marked readonly, so it can't change the agent's state either.
+
+```ts
+export class SupportChat extends ChatAgent<RequestContext, UserContext> {
+  canChat(userContext: UserContext | undefined) {
+    return userContext?.hasSupportAgent === true;
+  }
+}
+```
+
 ## Memory
 
 Return `memory: true` from `getAgentConfig()` to give each user a private memory with the agent, kept across all their chats in their `UserStore` (`AGENTS_USERS`). It's a writable block of the system prompt, which the model updates itself with `set_context`.
@@ -792,6 +810,7 @@ Imported from `@economic/agents` unless noted.
 | `configureContext()`                           | `Agent`     | Think's system prompt blocks. An override must include `...(await super.configureContext())`, or the agent's own prompt and rules are lost.                                                                                                                                                                                                                                                                                             |
 | `getTracingHandlers()`                         | `Agent`     | Destinations for completed turns and message feedback (default: `[]`).                                                                                                                                                                                                                                                                                                                                                                  |
 | `static getAuthenticator(env)`                 | `Agent`     | Optional caller authentication, credentials and user context.                                                                                                                                                                                                                                                                                                                                                                           |
+| `canChat(userContext)`                         | `Agent`     | Whether the user can send messages and answer approvals (default `true`). See [Reading without chatting](#reading-without-chatting).                                                                                                                                                                                                                                                                                                    |
 | `submitMessageFeedback` / `getMessageFeedback` | `ChatAgent` | Callable message feedback.                                                                                                                                                                                                                                                                                                                                                                                                              |
 | `getAgentConfig(ctx?)`                         | `Agent`     | Settings for a turn (default `{}`): `maxSteps`, `temperature`, `maxOutputTokens`, `topP`, `toolChoice`, `maxRetries`, `timeout`, `sendReasoning`, `providerOptions`; `toolCallLimits`, how often each user may call each tool by name, per day (`dailyCalls`) and per minute (`burst`), which needs `AGENTS_USERS`; for a chat, `memory`, a private memory per user, and `deleteMessagesAfterMs`, after which its messages are deleted. |
 | `agent`                                        | `Assistant` | Required. Your `ChatAgent` subclass.                                                                                                                                                                                                                                                                                                                                                                                                    |

package/dist/index.d.mts

@@ -12873,6 +12873,24 @@ export declare abstract class Agent<RequestContext extends Record<string, unknow
    */
   protected acceptsWithoutToken(_request: Request): boolean;
   onConnect(connection: Connection, ctx: ConnectionContext): Promise<void>;
+  /**
+   * Whether the user can send messages and answer approvals. When it's
+   * `false` they can still read the chat. Asked for each connection in
+   * `onConnect`, so an override of `onConnect` must call `super`. An error
+   * counts as `false`. `true` by default.
+   */
+  canChat(_userContext: UserContext | undefined): boolean | Promise<boolean>;
+  /** Answers still being asked, by connection, so messages sent meanwhile wait for them. */
+  private _canChatAnswers;
+  /**
+   * Asks `canChat` for a connection. A no marks it readonly, which outlives
+   * hibernation and the user's token.
+   */
+  private _askCanChat;
+  /** Whether the connection can chat. Calls from the server, without one, can. */
+  protected _canChat(connection?: Connection | undefined): Promise<boolean>;
+  /** Think stores a message before any hook runs, so it's refused before Think sees it. */
+  private _refuseChatMessages;
   protected _turn: CurrentTurnState<RequestContext, UserContext>;
   protected createToolContextForCurrentTurn(requestContext?: RequestContext): ToolContext<RequestContext, UserContext>;
   protected getToolContextForCurrentTurn(): ToolContext<RequestContext, UserContext> | undefined;

package/dist/index.mjs

@@ -71011,11 +71011,12 @@ var ToolApprovals = class {
 	}
 };
 // src/server/util/agent.ts
-function sendConnectionStatus(connection, status, reason) {
+function sendConnectionStatus(connection, status, reason, details) {
 	connection.send(JSON.stringify({
 		type: "connection_status",
 		status,
-		reason
+		reason,
+		...details
 	}));
 }
 function sendAgentType(connection, agentType) {
@@ -71204,6 +71205,7 @@ const THINK_SKILLS_CONTEXT_LABEL = "think_skills";
 const SESSION_CONTEXT_SEPARATOR = "═".repeat(46);
 const TOOL_CONTINUATION_PREFIX = "economic:tool-continuation:";
 const TOOL_CONTINUATION_REQUEST_PREFIX = "economic:tool-continuation-request:";
+const CHAT_REFUSED = "You can read this chat, but you can't chat in it.";
 /** Whether a tool call's output is the paused or running output of an execution. */
 function showsExecution(part, executionId) {
 	return "output" in part && part.output?.executionId === executionId;
@@ -71277,6 +71279,7 @@ var Agent = class Agent extends Think {
 		this._tracingHandlers = this.getTracingHandlers();
 		if (this.context.removeBlock(THINK_SKILLS_CONTEXT_LABEL)) await this.context.refreshSystemPrompt();
 		this._unfinishedToolCalls = await this._toolTaskSettlements.unfinishedToolCalls();
+		this._refuseChatMessages();
 		this.registerInstance();
 	}
 	/**
@@ -71336,7 +71339,57 @@ var Agent = class Agent extends Think {
 			connection.close(closeCode, message);
 			return;
 		}
-		sendConnectionStatus(connection, "connected");
+		sendConnectionStatus(connection, "connected", void 0, { canChat: await this._askCanChat(connection) });
+	}
+	/**
+	* Whether the user can send messages and answer approvals. When it's
+	* `false` they can still read the chat. Asked for each connection in
+	* `onConnect`, so an override of `onConnect` must call `super`. An error
+	* counts as `false`. `true` by default.
+	*/
+	canChat(_userContext) {
+		return true;
+	}
+	/** Answers still being asked, by connection, so messages sent meanwhile wait for them. */
+	_canChatAnswers = /* @__PURE__ */ new Map();
+	/**
+	* Asks `canChat` for a connection. A no marks it readonly, which outlives
+	* hibernation and the user's token.
+	*/
+	async _askCanChat(connection) {
+		const answer = Promise.resolve().then(() => this.canChat(this.identity.userContext())).catch((error) => {
+			logOperationalError("agent.can-chat.failed", error, this._logContext());
+			return false;
+		});
+		this._canChatAnswers.set(connection.id, answer);
+		const canChat = await answer;
+		if (!canChat) this.setConnectionReadonly(connection, true);
+		this._canChatAnswers.delete(connection.id);
+		return canChat;
+	}
+	/** Whether the connection can chat. Calls from the server, without one, can. */
+	async _canChat(connection = getCurrentAgent$1().connection) {
+		if (!connection) return true;
+		return await this._canChatAnswers.get(connection.id) ?? !this.isConnectionReadonly(connection);
+	}
+	/** Think stores a message before any hook runs, so it's refused before Think sees it. */
+	_refuseChatMessages() {
+		const onMessage = this.onMessage.bind(this);
+		this.onMessage = async (connection, message) => {
+			const event = typeof message === "string" ? parseProtocolMessage(message) : null;
+			if (!((event?.type === "chat-request" || event?.type === "tool-approval" || event?.type === "tool-result" && event.autoContinue === true) && !this._cf_connectionTargetsSubAgent(connection) && !await this._canChat(connection))) return onMessage(connection, message);
+			connection.send(JSON.stringify({
+				type: CHAT_MESSAGE_TYPES.CHAT_MESSAGES,
+				messages: this.messages
+			}));
+			if (event.type === "chat-request") connection.send(JSON.stringify({
+				type: CHAT_MESSAGE_TYPES.USE_CHAT_RESPONSE,
+				id: event.id,
+				body: CHAT_REFUSED,
+				done: true,
+				error: true
+			}));
+		};
 	}
 	_turn = {
 		inputTools: {},
@@ -71518,11 +71571,13 @@ var Agent = class Agent extends Think {
 	}
 	/** `all` also approves the tool call's later approvals, so it doesn't stop again. */
 	async approveExecution(executionId, options) {
+		if (!await this._canChat()) throw new Error(CHAT_REFUSED);
 		const answer = await this._toolApprovals.answer(executionId, true, { all: options?.all });
 		if (answer) return answer;
 		return super.approveExecution(executionId);
 	}
 	async rejectExecution(executionId, reason, options) {
+		if (!await this._canChat()) throw new Error(CHAT_REFUSED);
 		const answer = await this._toolApprovals.answer(executionId, false, { autoContinue: options?.autoContinue });
 		if (answer) return answer;
 		return super.rejectExecution(executionId, reason, options);
@@ -73499,6 +73554,10 @@ var ChatAgent = class extends Agent {
 	* The answer is the reply's text, or its JSON with `outputSchema`.
 	*/
 	async run(input, body) {
+		if (!await this._canChat()) return {
+			status: "error",
+			error: CHAT_REFUSED
+		};
 		const { inputSchema = z.string() } = await this.getAgentConfig(this.createToolContextForCurrentTurn(body));
 		const check = checkInputValue(inputSchema, input);
 		if (!check.success) return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@economic/agents",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "A starter for creating a TypeScript package.",
   "license": "MIT",
   "files": [