Skip to content

πŸ™Œ OpenHands: AI-Driven Development

refactor(types): use client error events (#16214)

Graham Neubig1f8a848c2aec
diff --git a/.agents/skills/custom-codereview-guide.md b/.agents/skills/custom-codereview-guide.md
index 1c3c3c716e..435198dbf1 100644
--- a/.agents/skills/custom-codereview-guide.md
+++ b/.agents/skills/custom-codereview-guide.md
@@ -122,6 +122,34 @@ If the updated package was uploaded **within the last 7 days**, treat it as a re
- **Server-Side Cleanup**: Endpoints that create persistent state (directories, files) must have rollback logic for partial failures β€” see the [Server Error Handling](#server-side-error-handling) section below
- **Cross-File Data Flow**: When new code calls existing APIs (constructors, factory methods), trace 1–2 levels into those APIs to verify the caller uses them correctly. Bugs often hide at layer boundaries where the caller's assumptions don't match the callee's behavior
+## Agent-Server Event Wire Contracts β€” Blocking Review Checkpoint
+
+For events received from the agent-server (REST history or WebSocket), the SDK
+Pydantic event model is the sole wire-contract authority. The TypeScript client
+must mirror that SDK contract, and Canvas must consume the client type.
+
+**Do not approve** a PR when any of the following is true:
+
+1. Canvas adds or retains a local interface for an event already exported by
+ `@openhands/typescript-client`, including a partial redeclaration,
+ intersection type, module augmentation, or Canvas-only optional field.
+2. A Canvas change adds a field to an SDK event shape without first adding it
+ to the SDK Pydantic model and then to the TypeScript client contract.
+3. A TypeScript-client event change was inferred from Canvas fixtures instead
+ of being verified against the SDK model serialization/schema.
+4. Canvas consumes an unreleased client commit or changes its client pin before
+ the corresponding client package has been published.
+
+When an event contract changes, require this order and evidence in the PR:
+
+1. SDK model/schema and serialization test.
+2. TypeScript-client mirror plus a fixture derived from the SDK JSON payload.
+3. Published client release and Canvas dependency update.
+4. Canvas rendering/telemetry test using the canonical client type.
+
+Canvas-only presentation state belongs in a separate view-model, keyed by an
+event ID; it must never be appended to the wire-event interface.
+
## Event Type Deprecation - Critical Review Checkpoint
When reviewing PRs that modify event types (e.g., `TextContent`, `Message`, `Event`, or any Pydantic model used in event serialization), **DO NOT APPROVE** until the following are verified:
diff --git a/__tests__/components/conversation-events/chat/group-events.test.ts b/__tests__/components/conversation-events/chat/group-events.test.ts
index 94900dccb5..61b79ce1b6 100644
--- a/__tests__/components/conversation-events/chat/group-events.test.ts
+++ b/__tests__/components/conversation-events/chat/group-events.test.ts
@@ -124,6 +124,7 @@ const makeTaskTrackerObservation = (
const makeAgentErrorEvent = (id: string): AgentErrorEvent => ({
id,
timestamp: new Date().toISOString(),
+ kind: "AgentErrorEvent",
source: "agent",
tool_name: "execute_bash",
tool_call_id: `call_${id}`,
diff --git a/src/types/agent-server/core/events/conversation-state-event.ts b/src/types/agent-server/core/events/conversation-state-event.ts
index e3c7454c02..744d55a872 100644
--- a/src/types/agent-server/core/events/conversation-state-event.ts
+++ b/src/types/agent-server/core/events/conversation-state-event.ts
@@ -1,5 +1,8 @@
import { BaseEvent } from "../base/event";
import { ExecutionStatus } from "../base/common";
+import type { ConversationErrorEvent } from "@openhands/typescript-client";
+
+export type { ConversationErrorEvent };
/**
* Token usage metrics for LLM calls
@@ -149,29 +152,6 @@ export type ConversationStateUpdateEvent =
| ConversationStateUpdateEventStats
| ConversationStateUpdateEventGoal;
-// Conversation error event - contains error information
-export interface ConversationErrorEvent extends BaseEvent {
- /**
- * Discriminator field for type guards
- */
- kind: "ConversationErrorEvent";
-
- /**
- * The source is always "environment" for conversation error events
- */
- source: "environment";
-
- /**
- * Error code (e.g., "AuthenticationError")
- */
- code: string;
-
- /**
- * Detailed error message
- */
- detail: string;
-}
-
// Server error event - contains error information
export interface ServerErrorEvent extends BaseEvent {
/**
diff --git a/src/types/agent-server/core/events/observation-event.ts b/src/types/agent-server/core/events/observation-event.ts
index bf4e22a709..2ef1188dd8 100644
--- a/src/types/agent-server/core/events/observation-event.ts
+++ b/src/types/agent-server/core/events/observation-event.ts
@@ -1,6 +1,9 @@
import { EventID, ToolCallID } from "../base/common";
import { BaseEvent } from "../base/event";
import { Observation } from "../base/observation";
+import type { AgentErrorEvent } from "@openhands/typescript-client";
+
+export type { AgentErrorEvent };
// Base interface for observation events
export interface ObservationBaseEvent extends BaseEvent {
@@ -47,26 +50,3 @@ export interface UserRejectObservation extends ObservationBaseEvent {
*/
action_id: EventID;
}
-
-// Agent error event
-export interface AgentErrorEvent extends BaseEvent {
- /**
- * The source is always "agent" for agent error events
- */
- source: "agent";
-
- /**
- * The tool name that this observation is responding to
- */
- tool_name: string;
-
- /**
- * The tool call id that this observation is responding to
- */
- tool_call_id: ToolCallID;
-
- /**
- * The error message from the scaffold
- */
- error: string;
-}
diff --git a/src/utils/transcript-export/index.test.ts b/src/utils/transcript-export/index.test.ts
index 957b775299..3f9c4fc357 100644
--- a/src/utils/transcript-export/index.test.ts
+++ b/src/utils/transcript-export/index.test.ts
@@ -174,6 +174,7 @@ describe("conversation transcript export", () => {
const errorEvent: AgentErrorEvent = {
id: "error-1",
timestamp,
+ kind: "AgentErrorEvent",
source: "agent",
tool_name: "terminal",
tool_call_id: "tool-error",