fix(sdk/go): address should-fix review items

#6 Fix broken godoc examples: add workspace parameter to all method
   calls in doc.go that were broken after workspace scoping.

#7 Add Err field to Event[T]: Watch error events now carry the
   underlying error instead of discarding it.

#8 Separate Unauthenticated from PermissionDenied: add
   ErrorUnauthenticated code and IsUnauthenticated() helper. gRPC
   Unauthenticated (401) now maps to its own code instead of
   collapsing into PermissionDenied (403).

#9 Add Unwrap to StatusError: replace dead Details field with Cause
   error field. StatusError.Unwrap() returns Cause, enabling
   errors.Is/As unwrapping. FromGRPCError and contextError both
   populate Cause.

Signed-off-by: Roland Huss <rhuss@redhat.com>

Author: rhuss

sdk/go/openshell/v1/doc.go

@@ -21,37 +21,37 @@
 //
 // # Sandbox Lifecycle
 //
-//	sandbox, err := client.Sandboxes().Create(ctx, "my-sandbox", &v1.SandboxSpec{
+//	sandbox, err := client.Sandboxes().Create(ctx, "default", "my-sandbox", &v1.SandboxSpec{
 //	    Template: &v1.SandboxTemplate{Image: "python:3.12"},
 //	    Environment: map[string]string{"LANG": "en_US.UTF-8"},
 //	}, nil)
 //	if err != nil {
 //	    log.Fatal(err)
 //	}
 //
-//	sandbox, err = client.Sandboxes().WaitReady(ctx, sandbox.Name)
+//	sandbox, err = client.Sandboxes().WaitReady(ctx, "default", sandbox.Name)
 //	if err != nil {
 //	    log.Fatal(err)
 //	}
 //
 // # Command Execution (available in a future release)
 //
-//	result, err := client.Exec().Run(ctx, sandbox.Name, []string{"echo", "hello"}, v1.ExecOptions{})
+//	result, err := client.Exec().Run(ctx, "default", sandbox.Name, []string{"echo", "hello"}, v1.ExecOptions{})
 //	if err != nil {
 //	    log.Fatal(err)
 //	}
 //	fmt.Println(string(result.Stdout)) // "hello\n"
 //
 // # Error Handling
 //
-//	_, err = client.Sandboxes().Get(ctx, "missing")
+//	_, err = client.Sandboxes().Get(ctx, "default", "missing")
 //	if v1.IsNotFound(err) {
 //	    // handle not found
 //	}
 //
 // # Watching
 //
-//	watcher, err := client.Sandboxes().Watch(ctx, sandbox.Name)
+//	watcher, err := client.Sandboxes().Watch(ctx, "default", sandbox.Name)
 //	if err != nil {
 //	    log.Fatal(err)
 //	}
@@ -65,7 +65,7 @@
 // Use StopOnTerminal to auto-close the watcher when the sandbox reaches a
 // terminal phase (Ready or Error):
 //
-//	watcher, err := client.Sandboxes().Watch(ctx, sandbox.Name,
+//	watcher, err := client.Sandboxes().Watch(ctx, "default", sandbox.Name,
 //	    v1.WatchOptions{StopOnTerminal: true},
 //	)
 //	if err != nil {
@@ -80,13 +80,13 @@
 //
 // Expose an HTTP service running inside a sandbox and retrieve its public URL:
 //
-//	endpoint, err := client.Services().Expose(ctx, "my-sandbox", "api", 8080, true)
+//	endpoint, err := client.Services().Expose(ctx, "default", "my-sandbox", "api", 8080, true)
 //	if err != nil {
 //	    log.Fatal(err)
 //	}
 //	fmt.Printf("Service URL: %s\n", endpoint.URL)
 //
-//	endpoints, err := client.Services().List(ctx, "my-sandbox")
+//	endpoints, err := client.Services().List(ctx, "default", "my-sandbox")
 //	if err != nil {
 //	    log.Fatal(err)
 //	}
@@ -98,15 +98,15 @@
 //
 // List available provider profiles and import new ones:
 //
-//	profiles, err := client.Providers().Profiles().List(ctx)
+//	profiles, err := client.Providers().Profiles().List(ctx, "default")
 //	if err != nil {
 //	    log.Fatal(err)
 //	}
 //	for _, p := range profiles {
 //	    fmt.Printf("%s (%s): %s\n", p.DisplayName, p.Category, p.Description)
 //	}
 //
-//	result, err := client.Providers().Profiles().Import(ctx, []v1.ProfileImportItem{
+//	result, err := client.Providers().Profiles().Import(ctx, "default", []v1.ProfileImportItem{
 //	    {Source: "openai-profile.yaml", Profile: v1.ProviderProfile{
 //	        DisplayName: "OpenAI",
 //	        Category:    v1.ProfileCategoryInference,
@@ -123,7 +123,7 @@
 //
 // Configure gateway-owned credential refresh for a provider:
 //
-//	status, err := client.Providers().Refresh().Configure(ctx, &v1.RefreshConfig{
+//	status, err := client.Providers().Refresh().Configure(ctx, "default", &v1.RefreshConfig{
 //	    Provider:      "openai",
 //	    CredentialKey:  "api-key",
 //	    Strategy:      v1.RefreshStrategyOAuth2ClientCredentials,
@@ -198,7 +198,7 @@
 // Note: CreateSession accepts a sandbox ID, not a name. For name-based access
 // with automatic session cleanup, prefer SSH().Tunnel() instead.
 //
-//	session, err := client.SSH().CreateSession(ctx, sandbox.ID)
+//	session, err := client.SSH().CreateSession(ctx, "default", sandbox.ID)
 //	if err != nil {
 //	    log.Fatal(err)
 //	}
@@ -207,7 +207,7 @@
 //	fmt.Printf("Host key: %s\n", session.HostKeyFingerprint)
 //	// Use session.Token to authenticate the SSH connection.
 //
-//	revoked, err := client.SSH().RevokeSession(ctx, session.Token)
+//	revoked, err := client.SSH().RevokeSession(ctx, "default", session.Token)
 //	if err != nil {
 //	    log.Fatal(err)
 //	}
@@ -217,7 +217,7 @@
 //
 // Forward a local connection to a port inside a sandbox:
 //
-//	conn, err := client.TCP().Forward(ctx, "my-sandbox", 5432)
+//	conn, err := client.TCP().Forward(ctx, "default", "my-sandbox", 5432)
 //	if err != nil {
 //	    log.Fatal(err)
 //	}
@@ -238,7 +238,7 @@
 // Use WithForwardServiceID to tag the forwarding session with a service
 // identifier for audit logging:
 //
-//	conn, err := client.TCP().Forward(ctx, "my-sandbox", 5432,
+//	conn, err := client.TCP().Forward(ctx, "default", "my-sandbox", 5432,
 //	    v1.WithForwardServiceID("billing-db"),
 //	)
 //
@@ -248,7 +248,7 @@
 // session creation, TCP forwarding with an SSH relay target, and automatic
 // session cleanup into one operation:
 //
-//	tunnel, err := client.SSH().Tunnel(ctx, "my-sandbox", 22)
+//	tunnel, err := client.SSH().Tunnel(ctx, "default", "my-sandbox", 22)
 //	if err != nil {
 //	    log.Fatal(err)
 //	}
@@ -269,15 +269,15 @@
 //
 // Use WithTunnelServiceID to associate a service identifier with the tunnel:
 //
-//	tunnel, err := client.SSH().Tunnel(ctx, "my-sandbox", 22,
+//	tunnel, err := client.SSH().Tunnel(ctx, "default", "my-sandbox", 22,
 //	    v1.WithTunnelServiceID("dev-ssh"),
 //	)
 //
 // # Sandbox Policy
 //
 // Set an initial security policy when creating a sandbox:
 //
-//	sandbox, err := client.Sandboxes().Create(ctx, "secure-sandbox", &v1.SandboxSpec{
+//	sandbox, err := client.Sandboxes().Create(ctx, "default", "secure-sandbox", &v1.SandboxSpec{
 //	    Template: &v1.SandboxTemplate{Image: "python:3.12"},
 //	    Policy: &v1.SandboxPolicy{
 //	        Version: 1,
@@ -302,7 +302,7 @@
 //
 // Replace the full policy at runtime via configuration update (available in a future release):
 //
-//	result, err := client.Config().Update(ctx, &v1.ConfigUpdate{
+//	result, err := client.Config().Update(ctx, "default", &v1.ConfigUpdate{
 //	    Name: "secure-sandbox",
 //	    Policy: &v1.SandboxPolicy{
 //	        Version: 2,
@@ -314,7 +314,7 @@
 //
 // Read a policy back from revision history (available in a future release):
 //
-//	revisions, err := client.Policy().List(ctx, "secure-sandbox")
+//	revisions, err := client.Policy().List(ctx, "default")
 //	if err != nil {
 //	    log.Fatal(err)
 //	}
@@ -328,7 +328,7 @@
 //
 // Read sandbox and gateway configuration, and update settings:
 //
-//	sbCfg, err := client.Config().GetSandbox(ctx, "my-sandbox")
+//	sbCfg, err := client.Config().GetSandbox(ctx, "default", "my-sandbox")
 //	if err != nil {
 //	    log.Fatal(err)
 //	}
@@ -343,7 +343,7 @@
 //	}
 //	fmt.Printf("Gateway settings revision: %d\n", gwCfg.SettingsRevision)
 //
-//	result, err := client.Config().Update(ctx, &v1.ConfigUpdate{
+//	result, err := client.Config().Update(ctx, "default", &v1.ConfigUpdate{
 //	    Name:       "my-sandbox",
 //	    SettingKey:  "max_tokens",
 //	    SettingValue: &v1.SettingValue{

sdk/go/openshell/v1/errors.go

@@ -22,6 +22,7 @@ const (
 	ErrorInternal         = types.ErrorInternal
 	ErrorUnimplemented    = types.ErrorUnimplemented
 	ErrorConflict         = types.ErrorConflict
+	ErrorUnauthenticated  = types.ErrorUnauthenticated
 )
 
 // StatusError is the typed error returned by all SDK operations.
@@ -54,3 +55,6 @@ func IsUnimplemented(err error) bool { return types.IsUnimplemented(err) }
 // IsConflict returns true if the error indicates a conflict, such as
 // optimistic concurrency or an invalid state transition.
 func IsConflict(err error) bool { return types.IsConflict(err) }
+
+// IsUnauthenticated returns true if the error indicates missing or invalid credentials.
+func IsUnauthenticated(err error) bool { return types.IsUnauthenticated(err) }

sdk/go/openshell/v1/errors_test.go

@@ -22,15 +22,17 @@ func TestStatusError_Error(t *testing.T) {
 	assert.Contains(t, s, "sandbox not found")
 }
 
-func TestStatusError_ErrorWithDetails(t *testing.T) {
+func TestStatusError_ErrorWithCause(t *testing.T) {
+	cause := fmt.Errorf("underlying issue")
 	err := &StatusError{
 		Code:    ErrorInvalidArgument,
 		Message: "bad name",
-		Details: map[string]string{"field": "name"},
+		Cause:   cause,
 	}
 	s := err.Error()
 	assert.Contains(t, s, "InvalidArgument")
 	assert.Contains(t, s, "bad name")
+	assert.ErrorIs(t, err, cause)
 }
 
 func TestIsNotFound(t *testing.T) {

sdk/go/openshell/v1/grpc_errors.go

@@ -13,10 +13,10 @@ func contextError(err error) error {
 	}
 	switch err {
 	case context.DeadlineExceeded:
-		return &StatusError{Code: ErrorDeadlineExceeded, Message: err.Error()}
+		return &StatusError{Code: ErrorDeadlineExceeded, Message: err.Error(), Cause: err}
 	case context.Canceled:
-		return &StatusError{Code: ErrorCancelled, Message: err.Error()}
+		return &StatusError{Code: ErrorCancelled, Message: err.Error(), Cause: err}
 	default:
-		return &StatusError{Code: ErrorInternal, Message: err.Error()}
+		return &StatusError{Code: ErrorInternal, Message: err.Error(), Cause: err}
 	}
 }

sdk/go/openshell/v1/internal/converter/errors.go

@@ -15,7 +15,7 @@ var grpcToSDK = map[codes.Code]types.ErrorCode{
 	codes.AlreadyExists:      types.ErrorAlreadyExists,
 	codes.Unavailable:        types.ErrorUnavailable,
 	codes.PermissionDenied:   types.ErrorPermissionDenied,
-	codes.Unauthenticated:    types.ErrorPermissionDenied,
+	codes.Unauthenticated:    types.ErrorUnauthenticated,
 	codes.InvalidArgument:    types.ErrorInvalidArgument,
 	codes.DeadlineExceeded:   types.ErrorDeadlineExceeded,
 	codes.Canceled:           types.ErrorCancelled,
@@ -49,5 +49,6 @@ func FromGRPCError(err error) error {
 	return &types.StatusError{
 		Code:    code,
 		Message: st.Message(),
+		Cause:   err,
 	}
 }

sdk/go/openshell/v1/sandbox_client.go

@@ -248,7 +248,7 @@ func (s *sandboxClient) Watch(ctx context.Context, workspace, name string, opts
 				default:
 					if recvErr != io.EOF {
 						select {
-						case ch <- Event[*Sandbox]{Type: EventError, Object: nil}:
+						case ch <- Event[*Sandbox]{Type: EventError, Err: recvErr}:
 						default:
 						}
 					}

sdk/go/openshell/v1/types/errors.go

@@ -23,6 +23,7 @@ const (
 	ErrorInternal
 	ErrorUnimplemented
 	ErrorConflict
+	ErrorUnauthenticated
 )
 
 // String returns the human-readable name of the error code.
@@ -48,6 +49,8 @@ func (c ErrorCode) String() string {
 		return "Unimplemented"
 	case ErrorConflict:
 		return "Conflict"
+	case ErrorUnauthenticated:
+		return "Unauthenticated"
 	default:
 		return fmt.Sprintf("Unknown(%d)", int(c))
 	}
@@ -57,13 +60,17 @@ func (c ErrorCode) String() string {
 type StatusError struct {
 	Code    ErrorCode
 	Message string
-	Details map[string]string
+	Cause   error
 }
 
 func (e *StatusError) Error() string {
 	return fmt.Sprintf("%s: %s", e.Code, e.Message)
 }
 
+func (e *StatusError) Unwrap() error {
+	return e.Cause
+}
+
 // IsNotFound returns true if the error indicates a resource was not found.
 func IsNotFound(err error) bool {
 	return hasCode(err, ErrorNotFound)
@@ -110,6 +117,11 @@ func IsConflict(err error) bool {
 	return hasCode(err, ErrorConflict)
 }
 
+// IsUnauthenticated returns true if the error indicates missing or invalid credentials.
+func IsUnauthenticated(err error) bool {
+	return hasCode(err, ErrorUnauthenticated)
+}
+
 func hasCode(err error, code ErrorCode) bool {
 	if err == nil {
 		return false

sdk/go/openshell/v1/types/watch.go

@@ -7,6 +7,7 @@ package types
 type Event[T any] struct {
 	Type   EventType
 	Object T
+	Err    error
 }
 
 // WatchInterface delivers a stream of typed events. Modeled after