Sawra/util fix

[sawradip]

Summary by CodeRabbit

• New Features

  • Enhanced structured response serialization across all SDKs
  • Improved error responses with expanded metadata fields (code, message, details, timestamp, request_id)
  • Better support for multiple response payload formats with fallback handling

• Bug Fixes

  • Fixed agent template ID handling
  • Corrected teardown confirmation logic
  • Improved console output formatting for agent execution

• Documentation

  • Added response format section with example JSON payload structure

• Chores

  • Version bumped to 0.1.26 across Python, Go, Rust, and TypeScript SDKs

[coderabbitai]

Caution

Review failed

The pull request is closed.

Walkthrough

This release bumps version to 0.1.26 across all SDKs (Python, Go, Rust, TypeScript) and introduces a unified response structure via AgentRunResponseMinimal. Client libraries are enhanced to deserialize multiple payload formats—supporting both new structured and legacy fields—while server endpoints and WebSocket handlers serialize responses using structured serializers for consistency.

Changes

Cohort / File(s)	Change Summary
Version and configuration 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	Version incremented from 0.1.25 to 0.1.26 across Python, Go, Rust, and TypeScript packages; CHANGELOG updated with bug fixes, features, and refactoring notes.
Client response deserialization runagent/client/client.py, runagent-go/runagent/pkg/client/client.go, runagent-rust/runagent/src/client/runagent_client.rs, runagent-ts/src/client/index.ts	Enhanced handling for multiple response payload shapes: checks for nested result_data.data, string-encoded JSON, and falls back to legacy output_data. Added structured deserialization methods with graceful fallback to original values on parsing failure.
Server response model runagent/utils/schema.py, runagent/sdk/server/local_server.py	Introduces new AgentRunResponseMinimal model with fields for success, data, message, error, timestamp, and request_id. Server endpoints refactored to use this minimal response type instead of AgentRunResponseV2, unifying error and success response paths.
API type definitions runagent-ts/src/types/index.ts	ApiResponse interface expanded with optional output_data field, message, timestamp, request_id fields; error field broadened from string to union type supporting both string and object with code/message/details/field properties.
Streaming and WebSocket handling runagent/sdk/server/socket_utils.py, runagent/sdk/socket_client.py	Outbound chunks serialized via serialize_object_to_structured() before sending; inbound streaming content deserializes via structured then object-based fallback paths with error cleaning; handlers preserve backward compatibility.
Serializer enhancement runagent-ts/src/serializer/index.ts	deserializeObject adds early handling for wrapped payloads with type and payload fields, attempting JSON parsing and recursive reconstruction before existing logic.
Documentation docs/cli/commands/run.mdx	Added "Response Format" section describing minimal JSON payload structure for completed executions, including fields like success, data, message, error, timestamp, and request_id.

Sequence Diagram

sequenceDiagram
    actor Client
    participant SDK as SDK Client
    participant Server as Run Server
    participant Serializer as Serializer

    rect rgb(200, 220, 255)
    note right of SDK: New Response Handling Path
    Client->>SDK: Call run()
    SDK->>Server: GET /run
    Server->>Serializer: serialize_object_to_structured(result)
    Serializer-->>Server: structured_json
    Server-->>SDK: AgentRunResponseMinimal {<br/>  success: true,<br/>  data: structured_json,<br/>  timestamp, request_id<br/>}
    end

    rect rgb(220, 255, 220)
    note right of SDK: Client Deserialization (Multiple Payloads)
    SDK->>SDK: Check response.data (nested/string/legacy)
    alt Nested: result_data.data
        SDK->>SDK: Extract result_data.data
    else String payload
        SDK->>Serializer: deserialize_object_from_structured(data)
        Serializer-->>SDK: deserialized object
    else Legacy: output_data
        SDK->>Serializer: deserialize_object(output_data)
        Serializer-->>SDK: deserialized object
    else Fallback
        SDK->>SDK: Return null or original
    end
    SDK-->>Client: payload (or null)
    end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

• Critical attention areas:
  • runagent/sdk/server/local_server.py: Extensive refactor replacing AgentRunResponseV2 with AgentRunResponseMinimal; verify all HTTP exception handlers and endpoint return paths correctly wrap responses and construct ErrorDetail payloads.
  • runagent/client/client.py, runagent-ts/src/client/index.ts, runagent-go/runagent/pkg/client/client.go, runagent-rust/runagent/src/client/runagent_client.rs: Multi-path response deserialization logic with nested fallbacks; ensure backward compatibility with legacy formats and that all parsing branches are tested.
  • runagent/utils/schema.py: AgentRunResponseMinimal added (appears duplicated per summary); verify no unintended duplicates and that ErrorDetail aligns with expanded error union in TypeScript ApiResponse.
  • runagent-ts/src/types/index.ts: ApiResponse generic default changed from unknown to JsonValue; confirm downstream type narrowing and error object typing (code/message/details/field) is compatible with client error handling.

Possibly related PRs

• Support: Add middleware API integration for local CLI #58: Modifies streaming data message handling and chunk serialization/deserialization, directly overlapping with this PR's WebSocket/socket_utils changes.
• Sawra/runagent cloud support wip #73: Prior refactor of response schemas and streaming/serialization codepaths (clients, socket_client, serializer) on which this PR builds the structured/minimal response pattern.
• Added examples and Rust SDK fix #78: Rust SDK client response handling fix that overlaps with the Rust client deserialization enhancements in this PR.

Poem

🐰 A version hops from 0.1.25 to 0.1.26,
With structured responses—no more complex tricks!
Clients now dance through legacy and new,
Deserializing payloads with a fallback or two. ✨
From server to socket, the data flows true,
Unified responses make SDKs brand new! 🎉

✨ 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/util_fix

---

📜 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 f552444 and ac455ad.

⛔ Files ignored due to path filters (1)

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

📒 Files selected for processing (18)

• CHANGELOG.md (1 hunks)
• docs/cli/commands/run.mdx (1 hunks)
• pyproject.toml (3 hunks)
• runagent-go/runagent/pkg/client/client.go (4 hunks)
• runagent-go/runagent/version.go (1 hunks)
• runagent-rust/runagent/Cargo.toml (1 hunks)
• runagent-rust/runagent/src/client/runagent_client.rs (1 hunks)
• runagent-ts/package.json (1 hunks)
• runagent-ts/src/client/index.ts (1 hunks)
• runagent-ts/src/serializer/index.ts (1 hunks)
• runagent-ts/src/types/index.ts (1 hunks)
• runagent/__init__.py (1 hunks)
• runagent/__version__.py (1 hunks)
• runagent/client/client.py (1 hunks)
• runagent/sdk/server/local_server.py (10 hunks)
• runagent/sdk/server/socket_utils.py (2 hunks)
• runagent/sdk/socket_client.py (2 hunks)
• runagent/utils/schema.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.}