Sawra/sdk fix ts

[sawradip]

Summary by CodeRabbit

• New Features

  • Introduced structured error handling with RunAgentExecutionError, providing error codes, messages, and actionable suggestions for all error scenarios across REST and WebSocket clients

• Documentation

  • Updated error handling guide with examples and usage patterns

• Chores

  • Version bumped to 0.1.30 across all SDKs
  • Enhanced release workflow security

[coderabbitai]

Caution

Review failed

The pull request is closed.

Walkthrough

Version bump to 0.1.30 across all SDKs paired with enhanced TypeScript error handling: introduction of RunAgentExecutionError class with structured properties (code, message, suggestion, details), updated REST and WebSocket clients to replace generic errors with this new error type.

Changes

Cohort / File(s)	Summary
Version Bumps CHANGELOG.md, pyproject.toml, runagent/__init__.py, runagent/__version__.py, runagent-go/runagent/version.go, runagent-rust/runagent/Cargo.toml, runagent-ts/package.json	Updated version identifiers from 0.1.29 to 0.1.30 across all SDKs and manifests.
TypeScript Error Infrastructure runagent-ts/src/errors/index.ts	New RunAgentExecutionError class with public properties: code, suggestion, details; default values for code and message on construction.
Type Augmentation runagent-ts/src/types/index.ts	Extended ApiResponse<T> error object shape with optional suggestion?: string | null field.
REST Client Error Enhancement runagent-ts/src/rest/index.ts	Added code-specific suggestion strings to all error branches (authentication, validation, connection, server, client, unknown).
Client-Side Error Handling runagent-ts/src/client/index.ts	Replaced generic Error throws with RunAgentExecutionError; introduced buildExecutionError helper to construct structured errors from API responses; added sanitizeMessage helper for normalized error messages.
WebSocket Base Error Handling runagent-ts/src/websocket/base.ts	Added buildStreamError and handleStatusMessage protected methods; augmented StreamMessage interface with optional message field; enhanced stream error construction with RunAgentExecutionError.
WebSocket Browser Implementation runagent-ts/src/websocket/browser.ts	Refactored status handling to use handleStatusMessage; replaced generic Error with RunAgentExecutionError for stream and connection errors; enhanced close/error event handling.
WebSocket Node.js Implementation runagent-ts/src/websocket/node.ts	Reworked status handling via handleStatusMessage; replaced inline error creation with buildStreamError; normalized caught errors to RunAgentExecutionError; improved close/error event messaging.
Documentation runagent-ts/README.md	Added RunAgentExecutionError to import examples; documented new Errors subsection describing error shape (code, message, suggestion) with usage example.

Sequence Diagram(s)

sequenceDiagram
    actor User
    participant Client as TypeScript Client
    participant REST as REST Client
    participant API as Backend API

    User->>Client: call run() or runStream()
    Client->>REST: makeRequest()
    REST->>API: HTTP request
    
    alt Success Response
        API-->>REST: 200 OK
        REST-->>Client: ApiResponse (data)
        Client-->>User: Success result
    else Error Response
        API-->>REST: 4xx/5xx Error
        REST->>REST: buildExecutionError()
        REST-->>Client: ApiResponse (error with code, message, suggestion)
        Client->>Client: throw RunAgentExecutionError
        Client-->>User: RunAgentExecutionError (code, suggestion, details)
    end

Loading

sequenceDiagram
    actor User
    participant Client as WebSocket Client
    participant WS as WebSocket Connection
    participant Backend as Backend Stream

    User->>Client: call runStream()
    Client->>WS: open connection
    WS->>Backend: initiate stream
    
    loop Stream Messages
        Backend-->>WS: StreamMessage
        WS->>WS: parseStreamMessage()
        WS->>WS: handleStatusMessage()
        
        alt Status: continue
            WS->>WS: emit data
        else Status: complete
            WS->>WS: resolveAll()
        else Status: error
            WS->>WS: buildStreamError()
            WS->>WS: rejectAll(RunAgentExecutionError)
        end
    end
    
    alt Unexpected Close/Error
        Backend--X WS: connection error
        WS->>WS: buildStreamError(CONNECTION_ERROR)
        WS->>WS: rejectAll(RunAgentExecutionError)
    end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

• Version bumps across 7 files are trivial and repetitive (low density)
• Error handling changes concentrated in TypeScript SDK span multiple interconnected files with new logic patterns:
  • New error class with initialization logic
  • New helper methods in client and WebSocket classes
  • Refactored control flow in REST and WebSocket implementations
  • Consistent patterns across browser and Node.js WebSocket implementations reduce review friction
• Type system changes are localized and straightforward
• Heterogeneous mix of simple version updates and moderate-complexity error handling refactoring moderates overall effort

Areas requiring extra attention:

• Logic in buildExecutionError and sanitizeMessage helpers in runagent-ts/src/client/index.ts to verify correct extraction of code/suggestion from API responses
• Flow changes in handleStatusMessage across WebSocket implementations to ensure all status paths (continue/complete/error/retry) are correctly handled
• Error propagation and rejection logic in runagent-ts/src/websocket/browser.ts and runagent-ts/src/websocket/node.ts to confirm consistent error wrapping

Possibly related PRs

• refactor: update GitHub Actions workflow and enhance TypeScript SDK #86: Modifies the same TypeScript SDK error handling pipeline (client, REST, WebSocket) to introduce structured RunAgentExecutionError and related request/streaming types.
• feat: added version command to see package version #60: Updates package version metadata across SDKs (version constants, manifests) similar to the version bump pattern in this PR.
• Sawra/util fix #85: Modifies ApiResponse shape and client error/payload handling in the TypeScript SDK, overlapping with error type augmentation.

Poem

🐰 Version hops to zero-three-oh! \
Error handling gets a glow—\
Structured suggestions light the way,\
WebSocket streams now save the day,\
TypeScript errors, finally clear! 🌟

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch sawra/sdk_fix_ts

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 5aa2fff and 4ee31b0.

⛔ Files ignored due to path filters (1)

• runagent-ts/package-lock.json is excluded by !**/package-lock.json

📒 Files selected for processing (15)

• CHANGELOG.md (1 hunks)
• pyproject.toml (3 hunks)
• runagent-go/runagent/version.go (1 hunks)
• runagent-rust/runagent/Cargo.toml (1 hunks)
• runagent-ts/README.md (3 hunks)
• runagent-ts/package.json (1 hunks)
• runagent-ts/src/client/index.ts (6 hunks)
• runagent-ts/src/errors/index.ts (1 hunks)
• runagent-ts/src/rest/index.ts (6 hunks)
• runagent-ts/src/types/index.ts (1 hunks)
• runagent-ts/src/websocket/base.ts (5 hunks)
• runagent-ts/src/websocket/browser.ts (3 hunks)
• runagent-ts/src/websocket/node.ts (3 hunks)
• runagent/__init__.py (1 hunks)
• runagent/__version__.py (1 hunks)

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}